Erreur Git 'is not a valid branch name' : Règles, Corrections et Conventions

Quand Git signale `fatal: 'some-name' is not a valid branch name`, cela signifie que la chaîne passée comme nom de branche viole la spécification refname de Git : l'ensemble des règles régissant ce qui constitue un nom de référence valide dans un dépôt Git. Git applique les mêmes règles aux noms de branches, de tags et de noms de suivi distant, car tous sont stockés comme références dans le répertoire `.git/refs/`.

La validation a lieu avant toute écriture d'objet. Git passe votre nom proposé par `check_refname_format()` en interne et abandonne avec l'erreur si le nom échoue. Cela signifie que vous voyez l'erreur immédiatement lors de l'exécution de `git checkout -b`, `git branch` ou `git switch -c` - il n'y a aucun état partiel à nettoyer.

Où l'apparition de l'erreur

• `git checkout -b branch-name` - créer une nouvelle branche et basculer dessus
• `git branch branch-name` - créer une nouvelle branche sans basculer
• `git switch -c branch-name` - l'équivalent moderne de checkout -b
• `git push origin branch-name` - pousser vers un dépôt distant avec un nom local invalide
• Scripts CI/CD - lorsqu'un nom de branche est construit programmatiquement à partir d'un ID de ticket ou d'un message de commit

La spécification refname de Git (définie dans la page man de `git-check-ref-format`) décrit un ensemble précis de caractères et de motifs interdits. Apprendre les règles une fois prévient toutes les erreurs de nommage futures - il n'y a aucun cas ambigu une fois la liste complète connue.

Caractères et séquences explicitement interdits

• Espace (ASCII 0x20) - l'erreur la plus courante ; utilisez `-` ou `_` à la place.
• Tilde `~` - utilisée dans la notation du reflog (`branch~2` signifie deux commits avant la pointe).
• Circonflexe `^` - utilisé dans la notation de révision (`branch^` désigne le commit parent).
• Deux-points `:` - utilisés dans la notation refspec de fetch (`refs/heads/main:refs/heads/main`).
• Point d'interrogation `?` - caractère joker glob dans les motifs de refs.
• Astérisque `*` - caractère joker glob dans les motifs de refs.
• Crochet ouvrant `[` - ouverture d'ensemble de caractères glob.
• Antislash `\\` - séparateur de chemin sous Windows ; interdit pour éviter les problèmes multiplateformes.
• Double point `..` - utilisé dans la notation de plage (`main..feature`).
• Séquence @{ - notation abrégée du reflog (`branch@{1}` est une entrée de reflog).

Règles positionnelles et structurelles

• Ne peut pas commencer par un point (`.`) - convention des fichiers cachés ; `.hidden` n'est pas un début valide.
• Ne peut pas se terminer par un point (`.`) - ambigu avec l'extension `.lock` et la notation d'extension de fichier.
• Ne peut pas se terminer par `.lock` - Git utilise le suffixe `.lock` pour les fichiers de verrouillage ; tout composant de chemin se terminant par `.lock` est interdit.
• Ne peut pas commencer par un tiret (`-`) - entre en conflit avec l'analyse des options de ligne de commande.
• Ne peut pas contenir de points consécutifs (`..`) - conflit avec la notation de plage (voir ci-dessus).
• Ne peut pas être le seul caractère `@` - abréviation de `HEAD`.
• Ne peut pas contenir de caractères de contrôle - les caractères ASCII inférieurs à 0x20 et DEL (0x7F) sont interdits.
• Ne peut pas être vide - une chaîne vide n'est pas un nom valide.

# ✓ Valid branch names
git checkout -b feature/add-login
git checkout -b fix/null-pointer-123
git checkout -b release/v2.1.0
git checkout -b chore_update-deps
git checkout -b users/alice/experiment

# ✗ Invalid - contains a space
git checkout -b "my feature"
# fatal: 'my feature' is not a valid branch name

# ✗ Invalid - double dot
git checkout -b feature..login
# fatal: 'feature..login' is not a valid branch name

# ✗ Invalid - ends with .lock
git checkout -b release.lock
# fatal: 'release.lock' is not a valid branch name

# ✗ Invalid - starts with hyphen
git checkout -b -hotfix
# fatal: '-hotfix' is not a valid branch name

La plupart des occurrences de cette erreur proviennent d'un petit nombre de motifs répétitifs. Chacun a une cause spécifique et une correction spécifique en une ligne.

Espaces issus de titres de tickets copiés-collés

Le déclencheur le plus courant est de copier un titre de ticket ou de story directement dans le nom de branche. « Add user login form » devient `git checkout -b Add user login form`, que Git interprète comme trois arguments séparés et rejette le nom de branche `Add`. Correction : remplacez chaque espace par un tiret. Beaucoup d'équipes automatisent cela avec un alias ou un script `branch-from-ticket` qui transforme le titre avant de le passer à Git. Le Générateur de Slugs convertit n'importe quel texte en slug propre séparé par des tirets, adapté aux noms de branches.

Caractères spéciaux dans l'interpolation de variables CI/CD

Les pipelines CI construisent souvent des noms de branches à partir de variables d'environnement - titres de PR, messages de commit ou IDs de tickets Jira. Si l'une de ces valeurs contient un caractère spécial (deux-points dans un ID Jira comme `PROJECT:123`, ou une barre oblique dans un tag semver comme `v1.0.0/rc.1`), le nom de branche interpolé échouera. Correction : assainissez l'entrée avant de l'utiliser comme nom de branche. Remplacez les caractères non alphanumériques par des tirets et supprimez les tirets et points en tête et en fin.

Point final ou suffixe .lock

Un nom de branche qui se termine par un point (`feature.`) ou par `.lock` (`release.lock`) échoue car Git réserve ces motifs aux fichiers de verrouillage. Cette erreur apparaît typiquement quand un développeur tape un nom se terminant par un point par accident, ou quand un script ajoute `.lock` dans un nom généré. Correction : retirez le point final, ou remplacez `.lock` par un suffixe valide comme `-locked` ou `-pending`.

Dans de rares cas - notamment avec d'anciennes versions de Git ou des branches créées via des outils tiers - vous pouvez vous retrouver avec un nom de branche invalide déjà présent dans votre dépôt. Le Git moderne l'empêche à la création, mais si vous héritez d'un dépôt avec un nom de branche problématique, voici comment le corriger.

Les règles refname de Git proprement dites constituent la base. Les plateformes d'hébergement distant ajoutent des restrictions supplémentaires : un nom qui passe la validation locale de Git peut quand même échouer lors du push vers GitHub ou GitLab. Comprendre les règles spécifiques aux plateformes évite la frustration d'un nom qui fonctionne localement mais échoue à distance.

Restrictions supplémentaires de GitHub

GitHub rejette les noms de branches se terminant par `.lock` sur n'importe quel composant de chemin (pas seulement le dernier segment), les noms contenant des points consécutifs à n'importe quelle position, et les noms contenant un octet nul. GitHub impose aussi une longueur maximale de nom de branche de 255 octets. L'interface web de GitHub supprime en outre les espaces en début et fin de fin des noms créés via l'interface.

Restrictions supplémentaires de GitLab

GitLab ajoute des restrictions pour les motifs de branches protégées : les noms contenant des jokers `*` sont réservés aux règles de branches protégées et ne peuvent pas servir de noms de branche littéraux. GitLab réserve aussi les noms correspondant à son namespacing interne comme `protected` et `refs`. Les noms de branches de plus de 255 caractères sont rejetés. La validation des noms dans le pipeline GitLab CI est distincte de la validation refname de Git : les erreurs d'interpolation de variables CI apparaissent comme des échecs de pipeline plutôt que comme des erreurs Git.

Considérations sur le système de fichiers Windows

Sous Windows, le répertoire `.git/refs/heads/` stocke chaque branche comme un fichier. Cela signifie que toutes les restrictions de noms de fichiers Windows s'appliquent : les noms ne peuvent pas contenir `<`, `>`, `"`, `|`, `?` ni `*` ; les noms ne peuvent pas se terminer par un espace ou un point ; et les noms sont insensibles à la casse sur NTFS. L'insensibilité à la casse est particulièrement importante dans les équipes mixtes - `Feature/Login` et `feature/login` sont la même branche sous Windows mais des branches différentes sur Linux et macOS.

Valide est le plancher, pas le plafond. Un nom de branche peut être valide selon les règles de Git tout en restant peu clair, incohérent ou inutilisable dans le flux de travail de votre équipe. Les conventions établies ajoutent de la prévisibilité par-dessus la validité technique - chaque membre de l'équipe peut lire un nom de branche et comprendre immédiatement son but, sa portée et son cycle de vie.

Convention Gitflow

Gitflow utilise cinq types de branches : `main` (production), `develop` (intégration), `feature/description`, `release/version` et `hotfix/description`. Les noms de branches utilisent la catégorie comme préfixe suivie d'une barre oblique et d'une description séparée par des tirets. Les branches de release incluent le numéro de version (`release/1.4.0`). Cette convention est bien prise en charge par la plupart des clients GUI Git et des outils CI, qui reconnaissent les préfixes comme catégories de branche.

GitHub Flow et conventions trunk-based

GitHub Flow utilise une structure plus simple : `main` plus des branches de fonctionnalités à courte durée de vie nommées de façon descriptive (`add-oauth-login`, `fix-pagination-bug`). Le développement trunk-based utilise de même `main` plus des branches très éphémères fusionnées en quelques heures. Les deux approches préfèrent des noms courts, en minuscules et séparés par des tirets sans préfixes de catégorie - l'hypothèse étant que les noms de branches sont temporaires et que le titre et la description du PR portent le contexte.

Conventions avec référence de ticket

Beaucoup d'équipes préfixent les noms de branches par une référence de ticket : `JIRA-1234-fix-login-bug` ou `feat/GH-456-add-dark-mode`. L'ID de ticket assure la traçabilité entre la branche et l'élément de travail d'origine. En construisant ces noms programmatiquement, assainissez toujours la partie description du ticket - les titres de tickets contiennent fréquemment des deux-points, des barres obliques et d'autres caractères qui cassent les règles de nommage Git.

Les noms de branches, comme les messages de commit, sont de la documentation. Une convention de nommage cohérente transforme votre liste de branches en un journal lisible des travaux en cours.

Corriger les erreurs une par une est réactif. La meilleure approche est d'empêcher la création de noms invalides dès le départ - via des outils de validation, des intégrations d'éditeur et des contrôles CI qui attrapent les problèmes avant qu'ils ne perturbent l'équipe.

Hooks Git de pre-push

Un script `.git/hooks/pre-push` s'exécute avant tout `git push` et peut valider le nom de la branche courante contre la convention de votre équipe. Si le nom échoue, le hook se termine avec un code non nul et interrompt le push avec un message explicatif. Utilisez le framework `pre-commit` pour distribuer les hooks de façon cohérente dans l'équipe - les fichiers `.git/hooks/` individuels ne sont pas committés dans le dépôt, mais un `.pre-commit-config.yaml` l'est.

Validation des noms dans le pipeline CI

Ajoutez une étape de validation de nom de branche au début de votre pipeline CI. Pour GitHub Actions, utilisez une étape de job précoce qui vérifie le nom de branche contre un motif regex et fait échouer le workflow en cas de non-correspondance. Cela attrape les noms techniquement valides selon Git mais violant la convention de l'équipe - noms sans préfixe de type, trop longs ou sans référence de ticket. Le Validateur de Convention de Noms de Branche applique cette même logique localement dans votre navigateur, utile pour vérifier un nom avant de créer la branche.

• Validez localement avant de créer : utilisez le Validateur de Convention de Noms de Branche pour vérifier les noms contre les règles Git et les conventions d'équipe.
• Utilisez un script de création de branche : une petite fonction shell qui prend un ID de ticket et une description et produit un nom de branche correctement formaté élimine entièrement les erreurs de nommage manuelles.
• Ajoutez un hook de pre-push : valide le nom de branche à chaque push - la dernière ligne de défense avant qu'un nom invalide n'atteigne le distant.
• Lintez en CI : une étape GitHub Actions ou GitLab CI qui valide le nom de branche à chaque PR empêche que les violations de convention ne soient fusionnées.
• Documentez la convention dans CONTRIBUTING.md : les membres d'équipe qui connaissent les règles font moins d'erreurs que ceux qui devinent à partir d'exemples.