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, который сам выбирает индексированные файлы, так не делает: когда ничего не проиндексировано, он ничего не проверяет и проходит.
Чего он не ловит
- Логику. Неверный путь, неверная опция tar или неверный порядок команд для ShellCheck — правильный скрипт.
- То, что происходит при запуске. Отсутствующий файл, неустановленную команду, переменную, которая пуста, потому что вызывающий её забыл. Запускайте скрипт и добавьте set -u, чтобы он останавливался на незаданных переменных.
- Код, которого он не видит. Текст, собранный во время работы и переданный в eval, и подключаемые файлы, если не включён external-sources.
- Всё, что касается возможности, которую он понимает неверно. Nameref и некоторые косвенные присваивания дают ложные тревоги; глушите их по одной и с причиной.
Автор статьи: Клавдия Кондакова