Revisar scripts Bash con ShellCheck y encontrar errores antes de ejecutarlos

Un script puede funcionar con informe.txt y fallar cuando recibe Informe ventas.txt. También puede pasar una comprobación de sintaxis y seguir utilizando mal las variables. En Bash, muchos errores aparecen cuando el dato real no se parece al ejemplo con el que empezamos.

ShellCheck es una herramienta de software libre que analiza scripts de shell y señala problemas habituales. No necesita ejecutar nuestro script para encontrar muchos de ellos. Podemos usarlo antes de lanzar una tarea que copia archivos, prepara una publicación o hace mantenimiento.

Vamos a utilizar un ejemplo que sólo cuenta líneas. Así podremos reproducir el fallo sin borrar datos ni probar una orden de administración sobre el sistema.

Icono de terminal de GNOME Adwaita

Icono de GNOME Project, bajo CC BY-SA 3.0.

Instalar ShellCheck

En Ubuntu y Linux Mint podemos instalarlo desde los repositorios:

sudo apt update
sudo apt install shellcheck
shellcheck --version

La página del proyecto recoge otras opciones de instalación. La versión disponible en la distribución no tiene por qué coincidir con la del servicio web o con la última release.

Para revisar un archivo no necesitamos sudo. Si el script contiene rutas privadas, tokens o configuración interna, prefiero utilizar la herramienta instalada en el ordenador. No hace falta pegarlo entero en una web para obtener el análisis.

ShellCheck analiza el texto. Eso es distinto de ejecutar Bash con el script, aunque después necesitaremos pruebas de comportamiento en un entorno controlado.

Un script válido que falla con un espacio

Guardamos lo siguiente como contar-error.sh:

#!/usr/bin/env bash
archivo=${1:-"Informe ventas.txt"}
wc -l $archivo

Parece que estamos pasando a wc el archivo cuyo nombre hemos recibido. Sin embargo, la expansión sin comillas puede dividir el valor en argumentos y tratar determinados caracteres como patrones.

La comprobación de sintaxis pasa:

bash -n contar-error.sh

Eso indica que Bash puede interpretar la estructura del archivo. No demuestra que la llamada reciba el nombre que nosotros teníamos en mente.

Para probarlo, creamos un documento ficticio dentro de una carpeta de pruebas:

printf 'Primera línea\nSegunda línea\nTercera línea\n' > "Informe ventas.txt"
bash contar-error.sh "Informe ventas.txt"

Utilizamos un nombre nuevo, no uno que ya contenga información que queramos conservar. El script intentará trabajar con Informe y ventas.txt como argumentos separados. Si esos archivos no existen, veremos los errores correspondientes.

En una tarea que modificase datos, la misma clase de fallo podría afectar a destinos distintos de los previstos. Por eso merece la pena encontrarlo antes de ejecutar una operación con consecuencias mayores.

Leer el aviso SC2086

Ahora analizamos el script:

shellcheck contar-error.sh

La herramienta señala la línea con wc -l $archivo y muestra el código SC2086. Ese identificador permite consultar la explicación de la regla y entender qué comportamiento intenta evitar.

Salida real de ShellCheck señalando SC2086 en la variable archivo

ShellCheck 0.11.0 señala la expansión sin comillas del script de ejemplo.

La corrección inmediata es pasar el valor entre comillas:

wc -l "$archivo"

Así el espacio forma parte de un mismo argumento. No hemos añadido las comillas para satisfacer una herramienta, sino para cambiar cómo Bash entrega el dato al comando.

Eso arregla el caso del espacio, pero todavía podemos mejorar el contrato del script. ¿Qué ocurre si no recibimos ningún argumento? ¿Y si el nombre empieza por un guion? Para una utilidad que vamos a reutilizar, conviene decidirlo.

Preparar una versión con entradas comprobadas

Esta versión, guardada como contar-correcto.sh, exige un archivo y cuenta sus líneas mediante la entrada estándar:

#!/usr/bin/env bash
if (( $# != 1 )); then
    printf 'Uso: %s archivo\n' "$0" >&2
    exit 2
fi
archivo=$1
if [[ ! -f "$archivo" ]]; then
    printf 'No existe un archivo regular: %s\n' "$archivo" >&2
    exit 1
fi
wc -l < "$archivo"

El primer bloque comprueba el número de argumentos. El segundo evita intentar leer una ruta que no sea un archivo regular. Los mensajes van al canal de error y usamos códigos de salida para que otra herramienta pueda distinguir el resultado.

La redirección abre el archivo y lo entrega a wc como entrada. El nombre ya no se interpreta como una opción de ese programa. Las comillas siguen siendo necesarias para que la ruta completa corresponda a un solo nombre.

Lo revisamos y ejecutamos sobre el ejemplo:

bash -n contar-correcto.sh
shellcheck contar-correcto.sh
bash contar-correcto.sh "Informe ventas.txt"

La salida de esta prueba es 3, las tres líneas terminadas con salto de línea que creamos. wc -l cuenta esos saltos, así que una última línea sin terminador merece una comprobación aparte si nuestro contrato necesita contarla de otra manera.

También probaría un archivo cuyo nombre empiece por guion, otro con corchetes y una ruta inexistente. En las pruebas del ejemplo, esos nombres válidos se procesaron y la ruta que faltaba devolvió un error. Llamarlo sin argumento produjo el mensaje de uso.

ShellCheck no es una prueba funcional

Un análisis sin avisos no demuestra que la tarea haga lo que queremos. La herramienta puede encontrar problemas de expansión o portabilidad, pero no sabe si hemos elegido la carpeta correcta de un cliente o si la regla de negocio requiere contar otra cosa.

Tampoco confirma que todos los comandos externos estén instalados, que tengamos acceso a una ruta o que un servicio responda. Eso necesita pruebas del proceso real, con datos de ejemplo y sin utilizar producción como laboratorio.

Para este script, combinaría tres comprobaciones: sintaxis con bash -n, análisis estático con ShellCheck y casos que verifican la salida y los errores. No utilizaría ninguna como sustituto de las otras.

Y si una herramienta de IA genera el script, aplicaría exactamente ese recorrido. Una explicación convincente no sustituye leer el archivo ni probar nombres diferentes al caso feliz.

Elegir Bash o sh de forma consciente

El encabezado del archivo ayuda a ShellCheck a identificar el lenguaje. Nuestro ejemplo utiliza construcciones de Bash, por eso empieza por #!/usr/bin/env bash y lo ejecutamos con bash.

Si ponemos #!/bin/sh pero usamos características propias de Bash, podemos introducir un problema de portabilidad. Ejecutarlo con sh archivo.sh tampoco convierte esas construcciones en compatibles.

Podemos pedir un análisis explícito con:

shellcheck --shell=bash contar-correcto.sh

En un script pensado para POSIX elegiríamos el dialecto correspondiente y escribiríamos el código para él. La documentación de opciones de ShellCheck explica cómo detecta el lenguaje y cómo forzarlo.

No cambiaría el encabezado sólo para que un aviso desaparezca. La elección tiene que coincidir con el intérprete que realmente ejecutará la tarea.

Incorporarlo al trabajo sin aplicar arreglos a ciegas

Podemos empezar pasando ShellCheck sobre los scripts que ya mantenemos y corrigiendo un problema cada vez. Después lo añadimos a una comprobación del proyecto o a la integración continua con una versión conocida.

No hace falta introducir un contenedor ni cambiar toda la configuración del repositorio para revisar un archivo. Un comando local puede ser suficiente para el primer paso.

Cuando aparezca un aviso, leería la línea y la explicación antes de cambiarla. Por ejemplo, entrecomillar un valor que contiene varias opciones no siempre produce los argumentos que queríamos. Si necesitamos representar una colección de argumentos, puede que corresponda utilizar un array, no una cadena separada por espacios.

También revisaría cualquier corrección automática como un diff normal. Que esté propuesta por el analizador no exime de entender qué cambia. Un fichero limpio de avisos pero con un comportamiento diferente tampoco es una mejora.

Qué hacer cuando un aviso no corresponde a nuestro caso

Hay situaciones en las que la herramienta no dispone del contexto completo o el código utiliza deliberadamente un comportamiento que detecta como problemático. Antes de silenciarlo, intentaría hacer esa intención más clara.

Si necesitamos una excepción, podemos limitarla a una línea o bloque mediante una directiva y explicar el motivo. No desactivaría todas las reglas para conseguir una salida verde ni añadiría un || true a la comprobación del proyecto para que cualquier fallo parezca éxito.

También conviene distinguir avisos de errores de la propia herramienta. Un archivo inexistente, una opción mal escrita o una diferencia de versiones pueden impedir el análisis. En una automatización, no queremos confundir eso con «no se encontraron problemas».

Si estamos aprendiendo Bash, la utilidad está precisamente en leer esos avisos y relacionarlos con entradas que podamos probar. Este ejemplo falla por un espacio, no por una operación compleja. Encontrarlo a tiempo nos permite escribir un script pequeño que seguirá siendo comprensible cuando lo retomemos más adelante.

Sergio Almela

Senior Software Engineer con más de diez años de experiencia. Escribo sobre Linux, software libre, backend, arquitectura, rendimiento, testing e IA aplicada al desarrollo.

Ver todas las entradas de Sergio Almela →