Vous avez fait une faute de frappe dans le nom d’une branche Git ? Le nom d’une fonctionnalité a changé et vous devez mettre votre branche à jour ? C’est une situation courante qui demande d’agir correctement pour ne pas créer de confusion.
Cet article vous donne les commandes exactes pour renommer une branche Git locale et distante sans rien casser. Vous trouverez la méthode complète, étape par étape, pour vous et pour synchroniser votre équipe.
Réponse Rapide : Les Commandes Essentielles pour Renommer une Branche Git
Si vous êtes pressé, voici les commandes dont vous avez besoin. Les sections suivantes expliquent en détail comment et pourquoi les utiliser.
Pour une Branche Locale
- Pour renommer la branche sur laquelle vous êtes :
git branch -m <nouveau-nom> - Pour renommer une autre branche depuis votre position actuelle :
git branch -m <ancien-nom> <nouveau-nom>
Pour une Branche Distante (Remote)
C’est un processus en 3 étapes :
- Renommez la branche en local :
git branch -m <nouveau-nom> - Poussez la nouvelle branche sur le remote :
git push origin -u <nouveau-nom> - Supprimez l’ancienne branche du remote :
git push origin --delete <ancien-nom>
Comment Renommer une Branche Locale Git ?
Renommer une branche en local est l’opération la plus simple. Git fournit une commande directe pour cela. La commande principale à connaître est `git branch -m`, où `-m` est le raccourci pour `–move` (déplacer).
Il existe deux scénarios principaux pour l’utiliser, en fonction de votre position actuelle dans votre dépôt.
Scénario 1 : Renommer la branche actuelle
Si vous êtes déjà sur la branche que vous voulez renommer (vérifiez avec `git status` ou `git branch`), la commande est très courte. Il suffit de spécifier le nouveau nom que vous souhaitez lui donner.
Par exemple, si vous êtes sur une branche nommée `feature/typo-fix` et que vous voulez la renommer en `feature/login-fix`, la commande est :
git branch -m feature/login-fixC’est tout. Votre branche locale a maintenant le nouveau nom.
Scénario 2 : Renommer une autre branche
L’autre option est de renommer une branche depuis une autre. C’est pratique si vous êtes sur `main` et que vous voulez corriger le nom d’une branche sans avoir à vous déplacer dessus. Pour cela, la commande demande deux arguments : l’ancien nom et le nouveau.
- Premier argument : le nom actuel de la branche (`
`). - Deuxième argument : le nom que vous voulez lui donner (`
`).
Si vous êtes sur `main` et que vous voulez renommer `feat/add-buttonn` en `feat/add-button`, vous tapez :
git branch -m feat/add-buttonn feat/add-buttonCas particulier : Forcer le renommage avec `-M`
Le flag `-M` (avec une majuscule) force le renommage. Il est surtout utile dans un cas précis : la sensibilité à la casse. Sur certains systèmes (comme macOS ou Windows), Git ne fait pas la différence entre `Feature/Login` et `feature/login`. Si vous voulez juste changer la casse, vous devez utiliser `-M`.
Par exemple, pour passer de `feature/login` à `Feature/Login` :
git branch -M Feature/LoginLa Méthode Complète pour Renommer une Branche Distante (Remote)
C’est ici que les choses demandent plus d’attention. Une information clé à retenir : vous ne pouvez pas directement renommer une branche distante. Il n’existe pas de commande `git rename-remote-branch`. Le processus consiste à créer une nouvelle branche sur le remote avec le bon nom, puis à supprimer l’ancienne.
La méthode est un processus en 3 étapes qui garantit que tout reste synchronisé et propre.
Étape 1 : Renommer votre branche locale
La première étape est celle que nous venons de voir. Vous devez d’abord renommer la branche sur votre propre machine. Assurez-vous d’être sur la branche en question pour plus de simplicité.
Si votre branche s’appelle `fix/bouton` et que vous voulez la changer en `fix/button` :
git branch -m fix/buttonÀ ce stade, votre branche locale s’appelle `fix/button`, mais elle est toujours liée à l’ancienne branche distante `origin/fix/bouton`.
Étape 2 : Pousser la nouvelle branche et configurer le suivi (tracking)
Maintenant, vous devez pousser votre branche locale renommée sur le dépôt distant. C’est cette action qui va créer la branche avec le nouveau nom sur le remote. Il faut utiliser une commande spécifique pour bien lier les deux.
La commande à utiliser est :
git push origin -u fix/buttonAnalysons cette commande :
git push origin: C’est la commande de base pour envoyer des modifications vers le remote nommé `origin`.fix/button: Le nom de votre nouvelle branche locale.-u(ou--set-upstream) : C’est la partie la plus importante. Elle indique à Git de lier votre branche locale `fix/button` à la nouvelle branche distante `origin/fix/button`.
Sans l’option `-u`, la branche serait poussée, mais le lien de suivi ne serait pas établi. Vous devriez le faire manuellement plus tard. Cette commande fait tout en une seule fois.
Étape 3 : Supprimer l’ancienne branche du remote
Votre dépôt distant contient maintenant deux branches : l’ancienne (`fix/bouton`) et la nouvelle (`fix/button`). Pour éviter toute confusion pour vous et votre équipe, il faut supprimer l’ancienne branche du remote.
La commande moderne et la plus claire pour faire ça est :
git push origin --delete fix/boutonBon à savoir : Vous croiserez peut-être une ancienne syntaxe pour supprimer une branche distante : git push origin :fix/bouton. Cette syntaxe fonctionne mais est moins lisible et plus sujette aux erreurs de frappe. La version avec --delete est recommandée car elle est explicite.
Une fois cette commande exécutée, votre remote est propre. Seule la branche avec le nouveau nom existe. Votre travail est terminé de votre côté.
L’Étape Cruciale : Communiquer et Synchroniser Votre Équipe
Si vous travaillez seul, vous pouvez vous arrêter là. Mais si vous êtes en équipe, cette dernière étape est la plus importante. Après avoir renommé une branche partagée, la communication est essentielle. Vos collaborateurs ont toujours une copie locale de l’ancienne branche qui pointe vers une référence distante qui n’existe plus.
Si un collègue essaie de faire un `git pull` ou `git push` sur l’ancienne branche, il recevra une erreur. Vous devez leur fournir une procédure simple pour mettre à jour leur dépôt local.
Recette à suivre pour vos collaborateurs :
Voici la séquence de commandes que votre équipe peut utiliser pour synchroniser son travail. Vous pouvez la copier-coller dans votre outil de communication (Slack, Teams, etc.).
-
Mettre à jour les références distantes et nettoyer les anciennes :
Cette commande récupère les changements du remote et supprime les références locales vers des branches qui n’existent plus.git fetch origin --prune -
Renommer leur branche locale :
Ils doivent se placer sur leur version locale de l’ancienne branche et la renommer.git checkout <ancien-nom> git branch -m <nouveau-nom> -
Relier la branche locale à la nouvelle branche distante :
Enfin, ils doivent mettre à jour le lien de suivi pour que leur branche locale pointe vers la nouvelle branche sur le remote.git branch --set-upstream-to=origin/<nouveau-nom>
Cette procédure garantit que tout le monde travaille sur la bonne branche et que le flux de travail n’est pas interrompu.
Cas Particuliers et Dépannage
Quelques situations spécifiques peuvent se présenter. Voici comment les gérer.
Comment renommer la branche `main` ou `master` ?
Le processus pour renommer la branche principale (`main` ou `master`) est techniquement le même que pour n’importe quelle autre branche. Cependant, il y a une étape supplémentaire très importante : vous devez changer la branche par défaut dans les paramètres de votre plateforme (GitHub, GitLab, Bitbucket).
Après avoir poussé la nouvelle branche (`main`) et supprimé l’ancienne (`master`), allez dans :
- Sur GitHub : Settings > Branches > Default branch.
- Sur GitLab : Settings > Repository > Default Branch.
Ceci garantit que les nouvelles Pull Requests et les clones du projet utiliseront la bonne branche par défaut.
Que deviennent les Pull Requests (PR) / Merge Requests (MR) ouvertes ?
C’est une source d’inquiétude fréquente. La bonne nouvelle est que la plupart des plateformes modernes gèrent ce changement automatiquement. Si vous renommez une branche qui a une Pull Request ouverte sur GitHub, GitHub mettra automatiquement à jour la PR pour qu’elle cible la branche renommée. Vous n’avez généralement rien à faire.
Que faire si `git status` indique que l’upstream a disparu ?
Parfois, après avoir renommé une branche locale, vous pouvez voir un message comme `Your branch is not tracking a remote branch`. Cela signifie que le lien de suivi a été perdu. La solution est de le rétablir manuellement avec la commande --set-upstream-to.
Par exemple, pour lier votre branche locale `feature/new-design` à `origin/feature/new-design` :
git branch --set-upstream-to=origin/feature/new-designFAQ – Questions fréquentes sur le renommage de branches Git
Voici les réponses aux questions les plus courantes sur le renommage de branches.
Quelle est la différence entre `git branch -m` et `git branch -M` ?
La version avec un -m minuscule est la commande standard. La version avec un -M majuscule est une commande « force ». Elle est utile si vous voulez juste changer la casse du nom d’une branche sur un système d’exploitation qui n’est pas sensible à la casse (comme Windows), ou si vous voulez renommer une branche vers un nom qui existe déjà, écrasant ainsi l’ancienne.
Renommer une branche affecte-t-il l’historique des commits ?
Non, l’historique des commits n’est pas affecté. Renommer une branche ne fait que changer un pointeur (une étiquette) qui désigne un commit spécifique. Tous les commits, leur ordre et leur contenu restent intacts.
Pourquoi utiliser `git push origin –delete` plutôt que l’ancienne syntaxe avec `:` ?
La commande git push origin --delete <nom-branche> est plus récente, plus explicite et plus sûre. L’ancienne syntaxe, git push origin :<nom-branche>, est plus facile à mal taper et peut prêter à confusion. Il est recommandé d’utiliser la version avec --delete pour plus de clarté.
Est-il plus sûr de renommer la branche depuis l’interface web de GitHub/GitLab ?
Oui, c’est une excellente option, surtout pour les débutants ou pour les branches partagées. GitHub, par exemple, permet de renommer une branche directement depuis son interface. L’avantage est que la plateforme s’occupe de beaucoup de choses pour vous, comme la mise à jour des Pull Requests et l’affichage d’instructions pour que vos collaborateurs mettent à jour leur copie locale.
Comment nettoyer les anciennes références de branches distantes de mon local ?
Après qu’un collaborateur a supprimé une branche distante, votre dépôt local peut encore conserver une référence « fantôme » à cette branche. Pour nettoyer cela, vous pouvez utiliser l’une des deux commandes suivantes :
git fetch --prune: Récupère les nouveautés du remote et supprime les références obsolètes.git remote prune origin: Fait uniquement le nettoyage, sans récupérer de nouvelles données.
Utiliser git fetch --prune est souvent la meilleure habitude à prendre.
