Linux / Commande help : consulter l’aide des commandes internes Bash

Dans Bash, help affiche la documentation des commandes internes et de certaines constructions du shell : essayez help cd, help read ou help for. Pour ne voir que la syntaxe, utilisez help -s nom ; pour un programme externe, recherchez plutôt son option d’aide ou sa page de manuel.

Comprendre ce que documente help

Une commande interne, ou builtin, est exécutée par le shell lui-même. C’est notamment nécessaire pour cd, qui doit changer le répertoire courant de ce shell, et utile pour read, qui affecte des variables dans son environnement d’exécution.

help connaît aussi des rubriques de syntaxe telles que if, for, while et [[. Ces constructions ne sont pas toutes des commandes internes ordinaires : le fait qu’une rubrique existe ne classe pas à lui seul le sujet comme un exécutable ou un builtin.

Cette aide appartient au Bash qui la fournit. Elle ne constitue pas un catalogue de tous les programmes Linux, n’interroge pas les index de man et ne nécessite pas un paquet de pages de manuel pour afficher ses propres rubriques. D’autres shells peuvent proposer une aide différente.

Afficher une rubrique et choisir le niveau de détail

La notation suivante décrit la syntaxe ; les crochets indiquent des arguments facultatifs et ne sont pas à recopier :

help [-dms] [motif ...]

Sans argument, la commande affiche les sujets disponibles. Avec un nom, elle affiche la rubrique correspondante :

help
help cd
help read
help printf

La sortie peut être longue : commencez par la forme courte si vous cherchez seulement la place des options et des arguments.

help -s read
help -s getopts
help -d cd
help -m cd

-m change la présentation : il n’ouvre pas man et n’installe aucune page. Dans un synopsis, une option entre crochets est facultative ; pour savoir ce qu’elle modifie, lisez ensuite l’aide détaillée. La syntaxe exacte peut évoluer avec Bash.

Pour consulter une construction du langage, passez son nom comme sujet. Les guillemets autour des symboles évitent notamment que le shell les développe comme des motifs de fichiers :

help if
help for
help while
help case
help '[['

La documentation officielle des commandes internes Bash précise les options de help et ses règles de sélection. Pour votre installation, help help fournit aussi une référence immédiatement disponible.

Rechercher plusieurs sujets avec un préfixe ou un motif

Distinguer le nom exact du préfixe

Lorsqu’un argument sans caractères de motif correspond exactement à une rubrique, Bash choisit cette rubrique. Sinon, il cherche les sujets dont le nom commence par cet argument. Ainsi, read et read* n’ont pas la même portée.

help -d read
help -d comp

La seconde recherche peut afficher compgen, complete et compopt, selon les sujets fournis par le Bash utilisé. Ce sont des noms de rubriques, pas des résultats d’une recherche dans toutes leurs explications.

Protéger les jokers contre l’expansion du shell

help -d 'read*'
help -d '*dir*'

Dans le premier motif, * accepte une suite de caractères après read : plusieurs rubriques, telles que read, readarray et readonly, peuvent correspondre. Le second cherche les noms contenant dir. Ces motifs sont de style shell, pas des expressions régulières.

Conservez les guillemets : sans eux, des fichiers du répertoire courant pourraient remplacer le motif avant que help ne le reçoive. Si vous connaissez la tâche mais pas le nom d’un programme externe, la recherche par mot-clé avec apropos répond à un autre besoin.

Choisir entre help, --help, man et info

Un même nom peut désigner un alias, une fonction, une commande interne ou un fichier exécutable. Examinez d’abord sa résolution dans la session où vous travaillez :

type cd
type read
type -a printf

Pour printf, la liste peut contenir le builtin et un programme externe. help printf documente celui de Bash ; il ne décrit pas automatiquement le fichier trouvé dans PATH. Un alias ou une fonction portant le même nom peut encore modifier ce qu’exécute une invocation ordinaire.

Le guide de man explique les sections et la recherche dans une page ; le guide de GNU Info explique la navigation dans les manuels à nœuds. Choisissez la documentation correspondant à l’outil et à la version réellement utilisés.

Dans Bash, cd --help peut également afficher l’aide de cd. Cela ne permet pas de conclure que toutes les commandes internes et tous les autres shells acceptent cette option. help cd indique plus clairement l’intention de consulter une rubrique Bash.

Passer de la documentation à un exemple reproductible

Supposons que vous vouliez lire une ligne en conservant ses espaces en bordure et ses barres obliques inverses. Consultez d’abord help read : -r empêche la barre oblique inverse de servir d’échappement. La variable IFS contrôle le découpage en champs ; une valeur vide évite ici ce découpage.

Exécutez cet exemple complet dans Bash. Les parenthèses créent un sous-shell, de sorte que la variable de l’exercice ne reste pas dans votre session :

(
  IFS= read -r ligne <<< '  un\chemin  '
  printf '[%s]\n' "$ligne"
)

La forme <<<, appelée chaîne en entrée ou here-string, fournit la chaîne à read avec une fin de ligne. Le résultat attendu contient deux espaces de chaque côté du texte et conserve la barre oblique inverse :

[  un\chemin  ]

Pour observer le rôle de -r, retirez uniquement cette option et relancez le même bloc : la barre oblique inverse devant c disparaît. Remettez ensuite -r ; cet essai ne crée aucun fichier et ne change aucun réglage persistant. Les pages d’aide décrivent les options, mais c’est leur combinaison avec les règles du shell qui explique ce résultat.

Lire avec un pager ou conserver l’aide dans un fichier

La sortie de help peut être envoyée à un programme de lecture comme less, si celui-ci est installé :

help -m read | less

Dans less, utilisez / pour chercher du texte et q pour quitter. Ce sont alors les touches du pager, pas des options de help.

Pour enregistrer l’explication dans un nouveau fichier du répertoire courant, sans écraser un fichier existant :

(
  set -o noclobber
  help -m read > read-help.txt
)

Si read-help.txt existe, la redirection échoue et son contenu est conservé. Choisissez alors un autre nom ou examinez le fichier existant. Le réglage noclobber reste limité au sous-shell. Une autre erreur d’écriture peut laisser un fichier incomplet : vérifiez le code de retour immédiatement après le bloc, puis son contenu, avant de considérer l’export comme réussi.

printf 'Code de retour : %s\n' "$?"
printf 'Bash : %s\n' "$BASH_VERSION"

Le fichier est une copie de l’aide à cet instant ; il n’est pas actualisé lorsque Bash change. Conservez la version avec vos notes si vous partagez cette explication ou la comparez à celle d’une autre machine.

Diagnostiquer une rubrique introuvable et vérifier le bon interpréteur

Une recherche d’aide n’est pas un test complet de fonctionnalité

Une rubrique correspondante donne normalement un statut nul. Une recherche sans résultat ou une option invalide échoue. Le test suivant consulte la rubrique sans analyser des phrases qui peuvent varier avec la langue ou la version :

if builtin help mapfile >/dev/null 2>&1; then
  printf '%s\n' 'Une rubrique mapfile est disponible.'
else
  printf '%s\n' 'Aucune rubrique mapfile utilisable avec cette recherche.'
fi

builtin demande ici la commande interne help plutôt qu’une fonction du même nom. Ce test constate la disponibilité d’une documentation ; il ne prouve pas que mapfile résolve vers la commande interne dans tous les contextes, ni que chaque option souhaitée soit acceptée.

Pour vérifier la catégorie réellement résolue, utilisez type -t mapfile ; pour une option ou un comportement précis, consultez la rubrique puis effectuez un essai limité aux données de test. Une commande peut être masquée par une fonction ou désactivée, alors que sa documentation est encore présente.

Un script lancé avec sh ne garantit pas les fonctions Bash

Le nom /bin/sh peut désigner un autre interpréteur. Inversement, le mode POSIX de Bash ne suffit pas à lui seul à expliquer la disparition de help : ne déduisez pas l’identité du shell du seul succès ou échec d’une commande.

Si votre script utilise les fonctions Bash de cet article, indiquez l’interpréteur dans le fichier :

#!/usr/bin/env bash

Cette ligne doit être la première du script et suppose que Bash soit disponible dans PATH. Vous pouvez aussi lancer explicitement bash fichier.sh. En revanche, sh fichier.sh choisit sh malgré cette première ligne. Évitez aussi de vous fier uniquement à $SHELL, qui ne garantit pas l’interpréteur exécutant le script courant.

Si le message indique qu’aucun sujet ne correspond, corrigez d’abord le nom ou simplifiez le motif. Si le sujet est un programme externe, consultez son aide propre. Si la commande help elle-même manque, identifiez le shell utilisé avant d’essayer d’installer un paquet portant ce nom.