Linux / Comando help: ajuda de comandos internos do Bash

help é o comando interno do Bash que mostra a ajuda dos seus comandos internos e de construções da linguagem. Use, por exemplo, help cd para consultar o cd do Bash e help for para ler a sintaxe do laço for. Essa documentação corresponde à versão do Bash em execução.

A forma básica é help tópico. Também é possível mostrar apenas a sintaxe, uma descrição curta ou uma apresentação semelhante à de um manual. Os exemplos a seguir pressupõem uma sessão Bash; em outro shell, o comando e os tópicos podem ser diferentes.

O que é o comando help?

Um comando interno, ou builtin, é executado pelo próprio processo do shell. cd muda o diretório de trabalho desse processo; read lê uma linha da entrada e atribui seus campos a variáveis; alias administra os aliases. Palavras reservadas como for são construções da linguagem, embora também tenham tópicos no help.

help fornece assistência não apenas para esses comandos internos do Bash, mas também para itens de sintaxe do shell como if, for, while, e [[. Em shells que não são Bash, a existência de comandos e o formato de saída podem diferir.

Sintaxe básica e exemplos de uso

O esquema abaixo descreve a sintaxe. Os colchetes indicam partes opcionais; substitua padrão pelo nome ou padrão do tópico. Não digite os colchetes literalmente.

help [-dms] [padrão]

Quando executado sem argumentos, ele exibe uma lista de comandos internos e itens de sintaxe para os quais o Bash fornece ajuda.

help

Para ver ajuda detalhada de um comando específico, especifique seu nome.

help cd
help read
help printf

Você pode verificar a sintaxe do shell da mesma maneira. É seguro colocar alguns símbolos entre aspas porque o shell pode interpretá-los primeiro.

help if
help for
help '[['

Opções do help

Ao escrever scripts e verificar rapidamente a colocação de argumentos, -s é útil.

help -s read
help -s getopts

Use -d se precisar de uma lista simples de descrições, e -m se precisar de explicações detalhadas separadas em parágrafos.

help -d cd
help -m cd

Encontrando múltiplos tópicos de ajuda com um padrão

Pesquisando por prefixo

Quando o argumento não contém curingas, o Bash tenta primeiro o nome exato do tópico. Se não o encontrar, procura nomes com esse prefixo. help comp, por exemplo, pode mostrar compgen, complete e compopt, conforme a versão instalada.

help comp

Usando padrões curinga

Se o padrão contiver caracteres de padrão de shell, todos os tópicos de ajuda correspondentes serão exibidos. Coloque o padrão entre aspas para evitar que ele seja expandido para nomes de arquivos no diretório atual primeiro.

help 'read*'
help '*dir*'

Você também pode pesquisar na lista inteira com grep, mas usar primeiro o recurso de padrão de help permite obter resultados com base nos nomes dos tópicos de ajuda.

Usando help após confirmar que é um comando interno

Se você não tiver certeza sobre o tipo de comando, verifique com type. Se o resultado for shell builtin, help frequentemente fornece a explicação mais direta.

type cd
type printf
type ls

Tanto os comandos internos do Bash quanto os arquivos executáveis externos podem existir, como printf. Para verificar todos os alvos possíveis que podem realmente ser executados, você pode executar o seguinte.

type -a printf

help printf explica o interno do Bash printf. Se você quiser conhecer o comportamento de um programa externo, você precisa verificar o --help ou o manual desse executável.

Diferenças entre help, --help e man

cd --help pode exibir a ajuda para o comando interno cd no Bash, mas você não deve esperar que o mesmo método funcione para todos os shells ou todos os comandos internos. É mais claro verificar comandos internos do Bash com base em help.

Exemplos de uso prático

Consultar as opções de read

read oferece opções de tempo limite, delimitador, tratamento de barras invertidas e atribuição a arrays. Compare a sinopse curta com a descrição detalhada para localizar a opção e seus argumentos.

help -s read
help read

Consultar condicionais e laços

Palavras reservadas e comandos compostos em scripts de shell também podem ser tópicos de ajuda.

help if
help while
help for
help case

Enviar a saída a um paginador ou arquivo

A saída normal de help pode ser enviada a um paginador, como less, ou a um arquivo. Use q para sair do less. O segundo comando abaixo cria read-help.txt no diretório atual; a redireção > substitui o conteúdo de um arquivo existente, portanto escolha antes um nome que possa usar.

help -m read | less
help -m read > read-help.txt

Depois da gravação, abra read-help.txt em um editor ou com less read-help.txt e confira se há conteúdo. O texto registrado corresponde à versão de Bash que o produziu. Antes de usar as mesmas opções em outro ambiente, compare a versão e a ajuda desse ambiente.

Verificando resultados de ajuda em um script shell

Se o tópico de ajuda solicitado existir, geralmente retorna um status de saída 0, e se nenhum tópico correspondente existir, retorna um valor diferente de zero. Você pode usar isso para verificar se um item de ajuda específico existe.

if help mapfile >/dev/null 2>&1; then
 printf '%s\n' 'A ajuda de mapfile está disponível.'
else
 printf '%s\n' 'A ajuda de mapfile não foi encontrada neste Bash.'
fi

Esse teste verifica a existência do tópico de ajuda, não garante que o comando esteja habilitado nem que seus argumentos sejam aceitos. A ajuda de um builtin desabilitado pode continuar disponível. Para identificar o que será executado, use type ou command -v; nomes também podem apontar para funções ou executáveis. Quando necessário, teste a funcionalidade desejada. Evite analisar frases da ajuda, que variam com a tradução e a versão.

Perguntas frequentes

Por que aparece no help topics match?

O nome que você digitou ou não é um tópico de ajuda do Bash ou não é fornecido na versão atual do Bash. Verifique o tipo de comando com type nome, e se for um programa externo, use comando --help ou man comando.

help não funciona em scripts sh

help é uma extensão de Bash, sem garantia de existência em um script portátil para sh. /bin/sh pode apontar para outro shell. O modo POSIX do próprio Bash não remove automaticamente o help: ele também funcionou no Bash 5.3.9 do Git for Windows usado para conferir os exemplos. Para scripts que dependem de Bash, escolha explicitamente um interpretador Bash disponível no sistema; verifique o caminho usado na execução.

É o mesmo comando, mas as explicações em help e man são diferentes.

Comandos internos e programas externos podem ter o mesmo nome. Você pode verificar os candidatos com type -a nome; para comandos internos do Bash, use help, e para arquivos executáveis externos, leia o manual do programa.

Preciso instalar o help separadamente?

Em instalações usuais, help faz parte do Bash e não requer um pacote separado. Outro shell pode não oferecê-lo. Se estiver ausente em um Bash específico, confirme o interpretador e a disponibilidade do builtin; compilações especiais podem omiti-lo ou ele pode estar desabilitado.

Posso pesquisar todos os comandos do Linux com help?

Não. O alvo principal do help são os comandos internos do Bash e a sintaxe do shell. Para comandos externos, use --help, man, info ou a documentação oficial.

Como mostrar apenas a sintaxe?

Use help -s tópico. Se você também precisar de uma descrição curta, use -d, e se precisar de um formato parecido com manual, use -m.

Resumo

help é a ferramenta mais direta para verificar comandos internos do Bash e a sintaxe do shell. Você pode ler explicações detalhadas com help tópico, verificar apenas a sintaxe com -s, e usar padrões para encontrar itens relacionados juntos.

Se você não tiver certeza sobre o tipo de comando, verifique-o primeiro com type. Use --help e man para programas externos, e para outros comandos básicos consulte a referência de comandos Linux em português.

Documentação oficial

• Documentação oficial de comandos integrados do GNU Bash
• Manual Oficial do GNU Bash
• Manual upstream bash(1) distribuído pelo Arch Linux