Gerador de Shellcheck Disable

ShellCheck e a diretiva disable

O ShellCheck é o analisador estático padrão de fato para scripts shell, escrito em Haskell por Vidar Holen e lançado em 2012 sob GPL. Ele faz parse de código sh, bash, dash e ksh e sinaliza centenas de armadilhas — de bugs de word-splitting a traps sutis de aspas que quebram o script só em casos específicos. Cada achado tem um código estável na faixa SC1000-SC2999 com uma página dedicada na wiki explicando o porquê e como corrigir.

Os achados mais comuns incluem SC2086 (proteger variáveis com aspas para evitar globbing/word-splitting — $var vira "$var"), SC2034 (variável atribuída mas nunca usada), SC2155 (declarar e atribuir separadamente para não perder o exit status), SC2046 (aspas em command substitution), SC2068 (usar "$@" e não $@), SC2002 (cat desnecessário), SC2129 (agrupar redirects com { } > arquivo) e SC2154 (variável referenciada mas não atribuída).

Sintaxe do disable

Quando o achado é intencional, silencie-o com uma diretiva na linha imediatamente acima do comando:

# shellcheck disable=SC2086
rm $arquivos   # word-splitting proposital aqui

# shellcheck disable=SC2086,SC2154
echo $talvez_nao_definida

# shellcheck disable=all
# (escopo de arquivo: colocar no topo, antes de qualquer código)

O escopo segue a posição: no topo do arquivo vale para o arquivo todo; acima de um comando, vale só para ele; dentro de uma função, escopada à função. Sempre combine o código com um comentário curto de justificativa — quem mantiver depois (e você daqui a seis meses) vai agradecer.

Integrações e CI

O ShellCheck integra com praticamente todo editor: VS Code via timonwong.shellcheck, Vim via ALE, Emacs via Flymake, Sublime via SublimeLinter. Em CI, rode em todo arquivo *.sh / *.bash do PR e quebre o build com warnings: GitHub Actions tem ludeeus/action-shellcheck; GitLab CI usa a imagem Docker oficial. O framework pre-commit oferece um hook que roda local antes de cada commit. Alternativas em nichos próximos: bashate (estilo OpenStack), shfmt (formatador, não linter) e shellharden (auto-fix de aspas).

Severidades e dialetos

Os achados vêm em quatro severidades: error, warning, info e style. Por padrão o ShellCheck assume bash; para scripts POSIX puros, adicione # shellcheck shell=sh no topo para que ele sinalize bashismos. Para lidar com variável indefinida de forma explícita, prefira ${var:-default} a silenciar o SC2154.

Perguntas frequentes

O ShellCheck funciona em zsh? Apenas parcialmente. Ele reconhece sintaxe comum mas não entende extensões específicas de zsh (arrays associativos com typeset -A, glob qualifiers, flags de expansão). Para zsh puro, use zsh -n para checagem de sintaxe e zshlint.

Posso rodar em scripts Fish? Não — o fish é um shell distinto com gramática não-POSIX. Use fish --no-execute para validação sintática.

Consigo adicionar regras customizadas? Não. O ShellCheck é deliberadamente prescritivo — o conjunto de regras é fixo pelos mantenedores. Se uma regra não cabe no projeto, desabilite por arquivo ou por linha; não forke a ferramenta.

Onde encontro a explicação de um código SC? Cada código tem uma página na wiki em github.com/koalaman/shellcheck/wiki/SC<código> com snippet problemático, snippet corrigido e exceções relevantes.