ShellCheck: ошибки в скриптах bash до их запуска

ShellCheck читает скрипт bash или sh, не запуская его, и сообщает об ошибках, из-за которых скрипт ломается на первом имени файла с пробелом, первой пустой переменной или первом cd в папку, которой нет. У каждой находки есть код, например SC2086, серьёзность и обычно предложенное исправление. Здесь он запускается на небольшом скрипте с типичными ошибками, ошибки исправляются, ложная тревога глушится, а проверка добавляется в хук pre-commit. Все команды выполнены с ShellCheck 0.11.0 в Ubuntu 24.04; вывод вставлен так, как он был напечатан.

Запуск ShellCheck

В Ubuntu и Debian есть пакет:

sudo apt install shellcheck

Но он отстаёт: Ubuntu 24.04 предлагает 0.9.0. Образ koalaman/shellcheck:stable от авторов содержит текущий выпуск, и ему не нужно ничего, кроме Docker. Его рабочая папка — /mnt, поэтому текущая папка монтируется туда:

docker run --rm koalaman/shellcheck:stable --version

ShellCheck - shell script analysis tool version: 0.11.0 license: GNU General Public License, version 3 website: https://www.shellcheck.net

С установленным пакетом каждый docker run ... ниже превращается просто в shellcheck с теми же опциями и именами файлов.

Первый отчёт

Скрипт упаковывает папку в архив с датой в имени. На машине автора он работает, и в нём шесть видов ошибок:

vi backup.sh

#!/bin/bash # backup.sh: pack a folder into a dated archive src=$1 dest=/tmp/backups name=backup-`date +%F`.tar.gz unused="old value" cd $dest for f in $(ls $src); do echo "Found $f" done tar czf $name $src if [ $? == 0 ]; then echo Done: $dest/$name fi

Копия этой первой версии сохраняется для следующих разделов:

cp backup.sh backup.orig

docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:stable backup.sh

In backup.sh line 5: name=backup-`date +%F`.tar.gz ^--------^ SC2006 (style): Use $(...) notation instead of legacy backticks `...`. Did you mean: name=backup-$(date +%F).tar.gz In backup.sh line 6: unused="old value" ^----^ SC2034 (warning): unused appears unused. Verify use (or export if used externally). In backup.sh line 8: cd $dest ^------^ SC2164 (warning): Use 'cd ... || exit' or 'cd ... || return' in case cd fails. Did you mean: cd $dest || exit In backup.sh line 9: for f in $(ls $src); do ^--------^ SC2045 (error): Iterating over ls output is fragile. Use globs. ^--^ SC2086 (info): Double quote to prevent globbing and word splitting. Did you mean: for f in $(ls "$src"); do In backup.sh line 12: tar czf $name $src ^---^ SC2086 (info): Double quote to prevent globbing and word splitting. ^--^ SC2086 (info): Double quote to prevent globbing and word splitting. Did you mean: tar czf "$name" "$src" In backup.sh line 13: if [ $? == 0 ]; then ^-- SC2181 (style): Check exit code directly with e.g. 'if mycmd;', not indirectly with $?. In backup.sh line 14: echo Done: $dest/$name ^---^ SC2086 (info): Double quote to prevent globbing and word splitting. Did you mean: echo Done: $dest/"$name" For more information: https://www.shellcheck.net/wiki/SC2045 -- Iterating over ls output is fragi... https://www.shellcheck.net/wiki/SC2034 -- unused appears unused. Verify use... https://www.shellcheck.net/wiki/SC2164 -- Use 'cd ... || exit' or 'cd ... |...

Код завершения — 1, если есть хотя бы одна находка, и 0, если нет ни одной: именно это нужно хуку или задаче CI.

Как читать отчёт

Каждый блок называет строку, цитирует её и отмечает точное место значком ^--^ под ней. Дальше идут код, серьёзность и сообщение, а у многих находок — строка «Did you mean» с исправленной строкой. У каждого кода есть своя страница в вики ShellCheck, и в конце отчёт перечисляет ссылки на самые серьёзные. Четыре уровня серьёзности, от самого серьёзного к самому лёгкому:

Уровни серьёзности
УровеньЗначениеЗдесь
errorскрипт будет работать неправильноSC2045: цикл по словам вывода ls ломается на именах с пробелами
warningочень вероятно ошибкаSC2164: если cd не сработал, скрипт продолжает в другой папке; SC2034: переменная, которую никто не читает
infoриск, который стоит убратьSC2086: переменная без кавычек делится на слова и раскрывается как шаблон
styleспособ написать лучшеSC2006: обратные кавычки; SC2181: проверка $? вместо самой команды

ShellCheck следит и за значениями: $dest в строках 8 и 14 не отмечен, потому что там всегда /tmp/backups, без пробелов и символов шаблона. $src приходит из командной строки и может содержать что угодно.

Исправление: автоматическая часть

-f diff печатает исправления «Did you mean» в виде патча вместо отчёта:

docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:stable -f diff backup.sh > fix.patch

cat fix.patch

--- a/backup.sh +++ b/backup.sh @@ -2,14 +2,14 @@ # backup.sh: pack a folder into a dated archive src=$1 dest=/tmp/backups -name=backup-`date +%F`.tar.gz +name=backup-$(date +%F).tar.gz unused="old value" -cd $dest -for f in $(ls $src); do +cd $dest || exit +for f in $(ls "$src"); do echo "Found $f" done -tar czf $name $src +tar czf "$name" "$src" if [ $? == 0 ]; then - echo Done: $dest/$name + echo Done: $dest/"$name" fi

У путей префиксы a/ и b/, как в диффе git, поэтому его применяет patch -p1 или git apply:

patch -p1 < fix.patch

patching file backup.sh

-f gcc печатает по одной строке на находку, в формате ошибок компилятора GCC, который понимают редакторы. Осталось три находки:

docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:stable -f gcc backup.sh

backup.sh:6:1: warning: unused appears unused. Verify use (or export if used externally). [SC2034] backup.sh:9:10: error: Iterating over ls output is fragile. Use globs. [SC2045] backup.sh:13:6: note: Check exit code directly with e.g. 'if mycmd;', not indirectly with $?. [SC2181]

Исправление: часть, где нужен человек

У трёх оставшихся нет механического исправления: нужна ли переменная, как перечислить файлы, какую команду проверять. Неиспользуемая переменная уходит, цикл использует шаблон, который сохраняет имена с пробелами целыми, а if проверяет сам tar. echo получает кавычки вокруг всего сообщения:

vi backup.sh

#!/bin/bash # backup.sh: pack a folder into a dated archive src=$1 dest=/tmp/backups name=backup-$(date +%F).tar.gz cd "$dest" || exit for f in "$src"/*; do echo "Found $f" done if tar czf "$name" "$src"; then echo "Done: $dest/$name" fi

Чистый скрипт ничего не печатает:

docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:stable backup.sh

Код завершения — 0.

Только важное: -S и -f gcc

На старом скрипте с сотнями находок начните с серьёзных. -S warning (--severity) скрывает info и style. На первой версии скрипта, сохранённой как backup.orig, остаются три находки:

docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:stable -S warning -f gcc backup.orig

backup.orig:6:1: warning: unused appears unused. Verify use (or export if used externally). [SC2034] backup.orig:8:1: warning: Use 'cd ... || exit' or 'cd ... || return' in case cd fails. [SC2164] backup.orig:9:10: error: Iterating over ls output is fragile. Use globs. [SC2045]

-S error оставляет только ошибки, -S style, уровень по умолчанию, показывает всё.

Как заглушить ложную тревогу

ShellCheck понимает не каждую возможность bash. Nameref, local -n into="$1", делает into другим именем переменной, чьё имя лежит в $1. Запись в into заполняет ту переменную, но ShellCheck видит присваивание, которое никто не читает:

printf 'one\ntwo\n' > a.txt && printf 'three\n' > b.txt

vi count.sh

#!/bin/bash # count.sh: line counts of files, kept in an associative array declare -A COUNT=() fill() { # $1: name of the array to fill, the rest: files local -n into="$1" local f for f in "${@:2}"; do into["$f"]=$(wc -l < "$f") done } fill COUNT a.txt b.txt for f in "${!COUNT[@]}"; do echo "$f ${COUNT[$f]}" done

docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:stable count.sh

In count.sh line 8: into["$f"]=$(wc -l < "$f") ^--------^ SC2034 (warning): into appears unused. Verify use (or export if used externally). For more information: https://www.shellcheck.net/wiki/SC2034 -- into appears unused. Verify use (...

При этом скрипт работает:

bash count.sh

a.txt 2 b.txt 1

Директива на строке перед командой выключает один код только для этой команды. Комментарий после неё — для следующего читателя:

vi count.sh

for f in "${@:2}"; do # shellcheck disable=SC2034 # into is a nameref: this fills COUNT into["$f"]=$(wc -l < "$f") done

docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:stable count.sh

Вывода нет, код завершения 0. Директива сразу после строки #! действует на весь файл. Выбирайте узкую, а ещё лучше код без директивы, когда он так же понятен: здесь функция могла бы печатать результаты, а массив заполнял бы вызывающий код. Тот же SC2034 на nameref однажды уронил коммит, который прошёл запуск хуков на изменённых файлах; эта история — в разделе Линтер, который ничего не проверил.

Настройки проекта: .shellcheckrc

Опции, которые действуют для всех скриптов проекта, пишут в .shellcheckrc в папке скрипта или в любой папке выше. Каждая строка — длинная опция без дефисов. Команда, которая принимает проверки $?, выключает SC2181 для всех скриптов:

printf 'disable=SC2181\n' > .shellcheckrc

docker run --rm -v "$PWD:/mnt" koalaman/shellcheck:stable -S style -f gcc backup.orig

backup.orig:5:13: note: Use $(...) notation instead of legacy backticks `...`. [SC2006] backup.orig:6:1: warning: unused appears unused. Verify use (or export if used externally). [SC2034] backup.orig:8:1: warning: Use 'cd ... || exit' or 'cd ... || return' in case cd fails. [SC2164] backup.orig:9:10: error: Iterating over ls output is fragile. Use globs. [SC2045] backup.orig:9:15: note: Double quote to prevent globbing and word splitting. [SC2086] backup.orig:12:9: note: Double quote to prevent globbing and word splitting. [SC2086] backup.orig:12:15: note: Double quote to prevent globbing and word splitting. [SC2086] backup.orig:14:22: note: Double quote to prevent globbing and word splitting. [SC2086]

Строки 13 в списке больше нет. Другие полезные строки — shell=bash для скриптов без строки #! и external-sources=true, чтобы ShellCheck читал файлы, которые скрипт подключает через source.

ShellCheck в pre-commit

Фреймворк pre-commit может запускать тот же образ. language: docker_image принимает имя образа как entry, монтирует репозиторий и передаёт индексированные файлы; types: [shell] выбирает скрипты shell по расширению и по строке #!:

git init -q demo && cd demo

git config user.email you@example.com && git config user.name You

vi .pre-commit-config.yaml

repos: - repo: local hooks: - id: shellcheck name: shellcheck language: docker_image entry: koalaman/shellcheck:stable types: [shell]

pre-commit install

pre-commit installed at .git/hooks/pre-commit

printf '#!/bin/bash\ncd $1\nls\n' > list.sh

git add . && git commit -qm "Adds list.sh"

shellcheck...............................................................Failed - hook id: shellcheck - exit code: 1 In list.sh line 2: cd $1 ^---^ SC2164 (warning): Use 'cd ... || exit' or 'cd ... || return' in case cd fails. ^-- SC2086 (info): Double quote to prevent globbing and word splitting. Did you mean: cd "$1" || exit For more information: https://www.shellcheck.net/wiki/SC2164 -- Use 'cd ... || exit' or 'cd ... |... https://www.shellcheck.net/wiki/SC2086 -- Double quote to prevent globbing ...

sed -i 's/^cd $1$/cd "$1" || exit/' list.sh && git add list.sh

git commit -qm "Adds list.sh"

shellcheck...............................................................Passed

Раз фреймворк передаёт имена файлов, хук проверяет и файлы, переданные в pre-commit run shellcheck --files .... Хук, написанный с pass_filenames: false, который сам выбирает индексированные файлы, так не делает: когда ничего не проиндексировано, он ничего не проверяет и проходит.

Чего он не ловит

Автор статьи: Клавдия Кондакова