Gestion des caractères spéciaux dans les noms de branche et de balise

Git est très permissif sur les caractères autorisés dans les noms de branche et d’étiquette. Lorsque vous utilisez Git à partir d’un interpréteur de commandes, il peut être nécessaire d'échapper ou de mettre entre guillemets des caractères spéciaux.

Dans cet article

À propos des noms de branche et de balise

La plupart des dépôts utilisent des noms de branche simples, tels que main ou update-icons. Les noms de balise suivent aussi généralement un format de base, tel qu’un numéro de version comme v1.2.3. Les noms de branche et les noms de balise peuvent également utiliser le séparateur de chemin (/) pour la structure, par exemple area/item ou level-1/level-2/level-3. En dehors de certaines exceptions — comme ne pas commencer ni terminer un nom par une barre oblique, ou avoir des barres obliques consécutives dans le nom — Git a très peu de restrictions sur les caractères qui peuvent être utilisés dans les noms de branche et de balise. Pour plus d’informations, consultez git-check-ref-format dans la documentation Git.

Pourquoi vous devez échapper les caractères spéciaux

Lorsque vous utilisez une interface CLI, vous pouvez avoir des situations où un nom de branche ou de balise contient des caractères spéciaux qui ont une signification particulière pour votre environnement shell. Pour utiliser ces caractères en toute sécurité dans une commande Git, ils doivent être placés entre guillemets ou échappés, sinon la commande peut avoir des effets inattendus.

Par exemple, le caractère $ est utilisé par de nombreux shells pour faire référence à une variable. La plupart des shells interprètent un nom de branche valide tel que hello-$USER comme équivalent du mot « hello », suivi d’un trait d’union et de la valeur actuelle de la variable USER, plutôt que comme la chaîne littérale hello-$USER. Si un nom de branche inclut le caractère $, le shell ne doit pas le développer en tant que référence de variable. De même, si un nom de branche contient un point-virgule (;), la plupart des "shells" informatiques l’interprètent comme un séparateur de commandes, ce qui implique qu'il doit être entre guillemets ou échappé.

Comment échapper les caractères spéciaux dans les noms de branche et de balise

La plupart des noms de branche et de balise avec des caractères spéciaux peuvent être gérés en incluant le nom entre guillemets simples, par exemple 'hello-$USER'.

  • Dans le shell Bash, l’insertion d’une chaîne de caractères entre guillemets simples conserve la valeur littérale des caractères entre guillemets simples.
  •         [Zsh](https://www.zsh.org/) se comporte comme Bash, mais ce comportement est configurable à l’aide de l’option `RC_QUOTES`.

  •         [PowerShell](https://microsoft.com/powershell) traite également les caractères de manière littérale à l’intérieur de guillemets simples.

Pour ces shells, l’exception principale est lorsque le nom de la branche ou de la balise contient un apostrophe. Dans ce cas, vous devez consulter la documentation officielle de votre shell :

  •         [Documentation Bash](https://www.gnu.org/software/bash/manual/)

  •         [Documentation Zsh](https://zsh.sourceforge.io/Doc/)

  •         [Documentation de Fish](https://fishshell.com/docs/current/)

  •         [Documentation PowerShell](https://docs.microsoft.com/en-gb/powershell/)

Nommage de branches et de balises

Si possible, créez des noms de branche et de balise qui ne contiennent pas de caractères spéciaux, car ceux-ci doivent être échappés. Un jeu de caractères par défaut sécurisé à utiliser pour les noms de branche et les noms de balise est :

  • L’alphabet anglais (a à z et A à Z)
  • Les chiffres (0 à 9)
  • Un ensemble limité de caractères de ponctuation :
  • point (.)
  • trait d’union (-)
  • trait de soulignement (_)
  • barre oblique (/)

Pour éviter toute confusion, vous devez commencer les noms de branche par une lettre.

Restrictions sur les noms dans GitHub

GitHub empêche un petit nombre de noms de branche et de tags d'être poussés vers le haut. Ces restrictions sont les suivantes :

  • Aucun nom qui ressemble à des ID d’objet Git (40 caractères contenant uniquement des chiffres 0-9 et des lettres A-F), pour éviter toute confusion avec les ID d’objet Git réels.
  • Aucun nom commençant par refs/, pour éviter toute confusion avec le nom complet des références Git. Pour plus d’informations sur les références, consultez Références Git dans la documentation Git.