Comando help in Bash: leggere la guida di builtin e sintassi della shell

help è il comando interno di Bash che mostra l’uso dei suoi comandi builtin e della sintassi della shell. Con help cd leggete la guida del cd eseguito da Bash; con help for consultate invece la sintassi di un ciclo. Per distinguere questi argomenti dalle pagine del sistema, confrontate anche la guida al comando man.

Usate help NOME, sostituendo NOME con il comando o l’argomento desiderato. Le opzioni permettono di limitare l’output alla sintassi, leggere una breve descrizione oppure ottenere un formato simile a una pagina di manuale.

Che cos’è help in Bash?

Un comando builtin è una funzionalità eseguita all’interno del processo della shell: non va confuso con una funzione definita in uno script. cd cambia la directory di lavoro della shell, read legge l’input e lo assegna a variabili, mentre alias gestisce gli alias.

help documenta anche parole riservate e comandi composti, tra cui if, for, while e [[. for è una parola riservata della sintassi Bash, non un normale builtin. Altre shell possono offrire strumenti diversi; questa guida riguarda Bash.

Sintassi di base ed esempi di utilizzo

help [-dms] [pattern]

Senza argomenti, help elenca i builtin e gli elementi di sintassi documentati dal Bash corrente.

help

Per leggere la guida dettagliata, indicate il nome. I comandi seguenti mostrano rispettivamente le istruzioni di cd, read e printf; non eseguono quelle operazioni.

help cd
help read
help printf

Potete consultare allo stesso modo la sintassi della shell. Mettete tra apici i simboli che potrebbero essere interpretati prima da Bash, come [[:

help if
help for
help '[['

Opzioni di help

Quando si scrivono script e si vuole controllare rapidamente la posizione degli argomenti, -s è utile.

help -s read
help -s getopts

Scegliete -d per una breve descrizione e -m per un testo organizzato con voci come NAME, SYNOPSIS e DESCRIPTION. Nomi delle voci e testo possono cambiare con la lingua e la versione.

help -d cd
help -m cd

Trovare più argomenti con un pattern

Ricerca per prefisso

Per un nome privo di caratteri speciali, Bash cerca prima una corrispondenza esatta; se non la trova, cerca i nomi che iniziano con quel prefisso. help comp può quindi mostrare compgen, complete e compopt, secondo la versione e la configurazione disponibili.

help comp

Usare i caratteri jolly

I caratteri jolly, come *, seguono le regole dei pattern della shell, non quelle delle espressioni regolari di grep. Gli apici impediscono che la shell trasformi il pattern in nomi di file della directory corrente prima di passarlo a help.

help 'read*'
help '*dir*'

help 'read*' può includere read, readarray e readonly; help '*dir*' cerca i nomi che contengono dir, come dirs. Il pattern riguarda i nomi degli argomenti, non una ricerca libera in tutto il testo. Se serve, potete filtrare l’elenco generale con grep.

Distinguere builtin, funzioni e programmi esterni

Prima controllate come Bash risolve il nome con type. shell builtin indica un comando interno; per un programma esterno vedrete normalmente un percorso. Alias e funzioni possono cambiare il risultato.

type cd
type printf
type ls

Uno stesso nome può identificare un builtin e un eseguibile esterno. type -a elenca le corrispondenze disponibili, così potete distinguere quale documentazione consultare.

type -a printf

help printf descrive il printf di Bash. Se vi interessa il programma esterno, consultate la sua documentazione; l’opzione --help è disponibile solo se quel programma la supporta.

Differenze tra help, --help e man

cd --help può stampare la guida del builtin in Bash, ma non è una convenzione universale. Inoltre, la stampa della guida non implica necessariamente uno stato di uscita 0: non usatela da sola come prova di disponibilità in uno script. Per consultare un builtin, preferite help NOME.

Esempi pratici di utilizzo

Verifica delle varie opzioni di read

read offre opzioni per timeout, delimitatori, descrittori di file e array. Con -s vedete la sintassi; nella guida completa cercate poi il significato delle opzioni che vi servono.

help -s read
help read

Verifica della sintassi per istruzioni condizionali e cicli

Le parole riservate e i comandi composti negli script shell possono essere anche argomenti di aiuto.

help if
help while
help for
help case

Leggere l’output con un pager o salvarlo in un file

L’output di help va allo standard output. Potete leggerlo con less e uscire dal pager con q. La seconda riga salva invece il testo in read-help.txt nella directory corrente: scegliete una directory scrivibile e un nome libero.

help -m read | less
(set -C; help -m read > read-help.txt)

La parentesi esegue set -C in una sottoshell: abilita noclobber, che impedisce alla redirezione di sovrascrivere un normale file esistente, senza cambiare l’impostazione della shell principale. Se il file esiste, Bash segnala l’errore: scegliete un altro nome. Dopo il successo, aprite il file e controllate che contenga le voci del manuale di read. Il testo riflette la versione e la lingua di quel Bash.

Controllare il risultato di help in uno script

Se il pattern trova un argomento, help restituisce normalmente 0; se non trova corrispondenze, restituisce uno stato diverso da zero e può scrivere un messaggio sullo standard error. L’esempio controlla l’esistenza della guida di mapfile, senza analizzarne il testo:

if help mapfile >/dev/null 2>&1; then
  printf '%s\n' 'La guida di mapfile è disponibile.'
else
  printf '%s\n' 'La guida di mapfile non è disponibile in questa shell.'
fi

Se la guida esiste, l’esempio stampa La guida di mapfile è disponibile.; altrimenti stampa il messaggio del ramo else. Questo verifica la documentazione, non tutte le capacità del builtin. Per controllare che un nome sia un builtin Bash potete usare type -t NOME; per sapere se un nome è risolvibile, command -v NOME. Quest’ultimo può trovare anche una funzione o un programma esterno. Per una specifica opzione serve una prova della relativa funzionalità.

Domande frequenti

help: errore nessun argomento di aiuto corrispondente

Il messaggio no help topics match indica che non è stato trovato un argomento corrispondente. Controllate nome, pattern e versione di Bash. Per un comando esterno, usate la documentazione del programma, NOME --help se supportato o man NOME, sostituendo il segnaposto.

help non funziona negli script sh

help appartiene a Bash e non è un comando richiesto dallo standard POSIX per tutte le shell. /bin/sh può avviare un’altra implementazione. La sola modalità POSIX di Bash non elimina automaticamente il builtin help. Verificate l’interprete effettivo e scegliete esplicitamente Bash se lo script ne richiede le funzionalità.

È lo stesso comando, ma le spiegazioni in help e man sono diverse.

Un builtin e un programma esterno possono avere lo stesso nome. Controllate con type -a NOME; poi leggete help NOME per il builtin oppure il manuale del programma esterno. Confrontate anche le versioni dei documenti e del programma.

Devo installare help separatamente?

Nelle normali installazioni di Bash è un builtin, quindi non serve un pacchetto help separato. Prima verificate di essere in Bash. Una compilazione particolare, un builtin disabilitato o una funzione con lo stesso nome possono richiedere controlli ulteriori con type -a help.

Posso cercare tutti i comandi Linux con help?

No. I suoi argomenti sono i builtin e la sintassi di Bash. Per un programma esterno cercate --help, man, info o la documentazione del progetto, secondo ciò che è disponibile.

Come vedere soltanto la sintassi breve?

Usate help -s NOME per la sintassi breve. -d mostra la descrizione breve, mentre -m organizza la guida come un manuale. La sintassi può occupare più righe, quindi -s non garantisce una sola riga fisica.

Scegliere la guida corretta

Per consultare un argomento Bash, partite da help NOME, limitatevi alla sintassi con -s oppure usate un pattern tra apici per cercare più nomi. Il testo appartiene al Bash che state eseguendo, un dettaglio utile quando confrontate sistemi o versioni diverse.

Se il nome può indicare più comandi, controllate prima type -a NOME. Per i builtin leggete la guida di Bash; per un eseguibile esterno scegliete il documento fornito da quel programma.

Documentazione di riferimento

• Manuale ufficiale di Bash distribuito da Debian: help e comandi builtin