Une branche Git porte parfois un nom choisi à la va-vite : « test », « truc », ou ce mystérieux « nouvelle-branche-2 » dont personne ne se souvient. Puis le projet avance, le nom devient trompeur et l’on aimerait remettre un peu d’ordre. Bonne nouvelle : renommer une branche est simple. Il suffit de choisir la bonne commande et de ne pas oublier que Git distingue votre dépôt local du dépôt distant.
Voici la méthode pas à pas, avec les commandes utiles, les précautions à prendre et quelques cas qui méritent un peu d’attention. L’objectif : donner à votre branche un nom clair sans dérégler le travail de l’équipe.
Avant de commencer : local ou distant ?
Une branche existe d’abord dans votre dépôt local, celui qui se trouve sur votre ordinateur. Elle peut aussi être publiée sur un dépôt distant, par exemple sur GitHub, GitLab ou un serveur d’entreprise. Ces deux versions sont liées, mais les modifier n’est pas la même opération.
La commande de renommage agit sur la branche locale. Si l’ancienne branche a déjà été envoyée sur le dépôt distant, il faudra ensuite publier la nouvelle et supprimer l’ancienne. C’est le petit détail qui transforme une opération de quelques secondes en source de confusion collective — surtout si l’équipe continue de travailler sur le vieux nom.
Pour voir les branches locales, utilisez :
git branch
La branche active est précédée d’un astérisque. Pour afficher également les branches distantes connues de votre dépôt local :
git branch -a
Avant toute modification, vérifiez que vous êtes dans le bon dépôt et que vous connaissez le nom exact de la branche. Git est précis ; il ne devine pas que « correction-menu » et « correction_menu » désignent, dans votre esprit, la même chose.
Renommer la branche sur laquelle vous travaillez
Si vous êtes déjà placé sur la branche à renommer, la commande est courte :
git branch -m nouveau-nom
Par exemple, si votre branche actuelle s’appelle « test » et que vous souhaitez la nommer « formulaire-contact », exécutez :
git branch -m formulaire-contact
L’option -m signifie que Git doit déplacer, ou renommer, la référence de branche. Vos fichiers et vos modifications ne sont pas effacés : vous changez le nom de la branche, pas le contenu de votre travail. Vérifiez le résultat avec git branch.
Cette méthode est pratique lorsque vous avez déjà commencé à travailler et que vous réalisez, en cours de route, que « test » ne raconte vraiment rien. Cela arrive. Un nom provisoire a une fâcheuse tendance à survivre jusqu’à la mise en production.
Renommer une autre branche
Vous n’avez pas besoin de quitter votre branche actuelle pour en renommer une autre. Il suffit d’indiquer à Git le nom existant, puis le nouveau :
git branch -m ancien-nom nouveau-nom
Imaginons que vous soyez sur « accueil » et que vous vouliez renommer « modif-couleurs » en « refonte-palette » :
git branch -m modif-couleurs refonte-palette
Git met à jour le nom de la branche locale. Le contenu des commits reste identique. Si le nom choisi est déjà utilisé par une autre branche, Git refusera généralement l’opération plutôt que d’écraser une référence existante. Dans ce cas, choisissez un nom disponible ou examinez d’abord les branches présentes.
Vous pouvez consulter les branches locales avec git branch. Si vous avez besoin d’un aperçu plus complet des références locales et distantes, utilisez git branch -a.
Vérifier le nouveau nom et l’état du dépôt
Après le renommage, prenez quelques secondes pour vérifier que tout correspond à vos attentes :
git branch
Si vous êtes sur la branche concernée, son nouveau nom apparaît dans la liste avec un astérisque. Vous pouvez aussi vérifier l’état de votre espace de travail :
git status
Cette commande vous indique notamment la branche active et signale les modifications non enregistrées. Renommer une branche ne supprime pas ces modifications, mais il reste utile de savoir précisément où vous en êtes avant de publier quoi que ce soit.
Vous pouvez également consulter le nom de la branche active avec :
git branch --show-current
Cette vérification est particulièrement bienvenue dans un projet qui comporte beaucoup de branches. Entre « correction-entete », « correction-en-tete » et « correction-entete-final », une seconde de contrôle peut éviter une demi-heure de perplexité.
Publier la branche renommée sur le dépôt distant
Si la branche n’a jamais été publiée, il suffit de l’envoyer sous son nouveau nom en définissant son lien de suivi :
git push -u origin nouveau-nom
Par exemple :
git push -u origin formulaire-contact
Dans cette commande, origin est le nom courant du dépôt distant. L’option -u établit un lien de suivi entre votre branche locale et la branche distante. Ainsi, lors des prochains envois ou récupérations, vous pourrez généralement utiliser simplement git push ou git pull.
Si le dépôt distant porte un autre nom, remplacez origin par ce nom. Pour consulter les dépôts distants configurés, lancez :
git remote -v
Mettre à jour une branche déjà publiée
Si l’ancienne branche existe déjà sur le dépôt distant, le renommage local ne modifie pas automatiquement son nom là-bas. Il faut publier la nouvelle branche, puis supprimer l’ancienne référence distante.
Commencez par envoyer la branche renommée et définir son lien de suivi :
git push -u origin nouveau-nom
Ensuite, supprimez l’ancien nom du dépôt distant :
git push origin --delete ancien-nom
Par exemple, pour remplacer « test » par « formulaire-contact » :
git push -u origin formulaire-contact
git push origin --delete test
La première commande publie la nouvelle branche. La seconde efface l’ancienne du dépôt distant, mais pas vos commits locaux. Avant de la lancer, vérifiez donc que le nouveau nom est bien publié et que vos collègues savent qu’il a changé. Si quelqu’un envoie encore des modifications vers l’ancien nom, le dépôt risque de retrouver une branche que vous pensiez avoir rangée.
Prévenir les personnes qui travaillent sur la branche
Dans un travail individuel, le renommage est presque toujours transparent. Dans une équipe, c’est une modification visible par les autres : leurs dépôts locaux peuvent encore contenir l’ancien nom, et leurs commandes peuvent continuer à pointer vers lui.
Un bref message dans l’outil de suivi ou le canal de l’équipe suffit souvent : « La branche “test” a été renommée en “formulaire-contact”. Récupérez la nouvelle branche avant de poursuivre. » Ce n’est pas spectaculaire, mais c’est nettement plus efficace que de découvrir deux jours plus tard que chacun travaille de son côté sur une version différente.
Les collègues peuvent actualiser leurs références distantes avec :
git fetch --prune
L’option --prune retire de leur liste les références distantes qui n’existent plus sur le serveur. Pour passer ensuite sur la nouvelle branche, ils peuvent utiliser :
git switch formulaire-contact
Si cette branche n’est pas encore présente localement, Git peut créer la branche locale à partir de la référence distante, selon la configuration et la version utilisées. Au besoin, une commande explicite permet de créer la branche locale en la reliant à la branche distante :
git switch --track origin/formulaire-contact
Si un collègue avait déjà une branche locale fondée sur l’ancien nom, il peut choisir de la renommer lui aussi, ou de la supprimer si elle ne contient aucun travail à conserver. Avant toute suppression locale, qu’il vérifie ses commits et ses modifications : mieux vaut prendre une seconde de prudence que tenter de reconstituer une journée de travail.
Renommer une branche en changeant seulement les majuscules
Un cas particulier mérite une mention : remplacer un nom par un autre qui ne diffère que par les majuscules, comme « accueil » et « Accueil ». Certains systèmes de fichiers ne distinguent pas toujours ces deux écritures. Le renommage peut alors échouer ou produire un résultat déroutant.
Une solution consiste à passer par un nom temporaire :
git branch -m accueil nom-temporaire
Puis à effectuer le second renommage :
git branch -m nom-temporaire Accueil
Si la branche existe sur le dépôt distant, publiez également le nouveau nom et supprimez l’ancienne référence distante, comme expliqué plus haut. Les différences de casse peuvent sembler minuscules à l’écran ; pour Git et les systèmes qui hébergent le dépôt, elles ne sont pas toujours anodines.
Que faire si le renommage échoue ?
Le message d’erreur donne souvent la piste. Si Git indique que le nouveau nom existe déjà, listez les branches et choisissez un autre nom ou vérifiez si la branche existante peut être supprimée. Si la branche contient des modifications non enregistrées, le renommage reste généralement possible, mais prenez le temps de vérifier votre état avec git status.
Si Git ne trouve pas l’ancien nom, contrôlez son orthographe avec git branch. Les noms de branches sont sensibles aux différences de caractères et d’écriture : un tiret, une barre oblique ou une majuscule mal placés suffisent à faire échouer la commande.
Enfin, si une demande de fusion existe déjà sur GitHub ou GitLab, le renommage peut avoir des effets sur son affichage ou son suivi, selon la plateforme et le contexte. Avant de supprimer l’ancienne branche distante, vérifiez que la demande de fusion est toujours correctement associée et que le travail de l’équipe n’en dépend pas. Dans le doute, informez les personnes concernées avant d’agir.
Choisir un nom qui restera compréhensible
Renommer une branche prend peu de temps ; choisir un nom utile demande un peu plus de soin. Un bon nom donne une idée du travail effectué sans obliger l’équipe à ouvrir la branche pour le découvrir. Par exemple, « ajout-paiement-en-ligne » ou « correction-menu-mobile » sont plus parlants que « truc », « essai » ou « version-finale-vraiment ».
Si votre équipe utilise une convention, respectez-la. Certaines équipes ajoutent une catégorie comme « fonctionnalite/ », « correction/ » ou un numéro de tâche : par exemple, « correction/248-menu-mobile ». L’important est de choisir une règle commune et de l’appliquer avec constance. La meilleure convention reste celle que tout le monde comprend — y compris la personne qui reprendra le projet dans six mois, avec un café froid et une patience limitée.
En résumé, pour renommer une branche locale active, utilisez git branch -m nouveau-nom. Pour renommer une autre branche, précisez les deux noms. Si elle est déjà publiée, envoyez le nouveau nom avec git push -u origin nouveau-nom, puis supprimez l’ancien nom distant avec git push origin --delete ancien-nom. Vérifiez toujours le résultat et prévenez l’équipe : Git s’occupe des références, mais pas de la communication.
