git branch

Branches et fusions

Lister, créer ou supprimer des branches

La commande 'git branch' permet de créer, lister, renommer et supprimer des branches. Elle ne permet pas de changer de branche - utilisez 'git switch' ou 'git checkout' pour cela. Dans Git, les branches sont des pointeurs légers vers des commits, ce qui rend la création et le changement de branche extrêmement rapides. Sans argument, git branch liste les branches existantes en mettant en avant la branche courante. Avec un nom de branche, elle crée une nouvelle branche qui pointe sur le HEAD actuel. Les branches sont essentielles au développement en parallèle : plusieurs fonctionnalités ou correctifs peuvent avancer en même temps sans se gêner.

Synopsis

git branch [--list] [-a | -r] [-v [--abbrev=<n> | --no-abbrev]] [--merged | --no-merged] [<pattern>...]
git branch <branch-name> [<start-point>]
git branch (-d | -D) [-r] <branch-name>...
git branch (-m | -M) [<old-branch>] <new-branch>
git branch (-c | -C) [<old-branch>] <new-branch>
git branch [--set-upstream-to=<upstream> | -u <upstream>] [<branch-name>]
[ ] facultatif| ou<arg> valeur à remplacer... répétable--flag option

Options

Cliquez sur une option pour la déplier

Débutant (7)

Lister les branches qui correspondent à un ou plusieurs motifs génériques du shell. Sans motif, liste toutes les branches locales. L’option --list est obligatoire pour filtrer - sinon Git prend le motif pour le nom d’une nouvelle branche à créer.

RecommandéNécessaire pour filtrer par motif ; sans lui, un motif crée une branche

Exemple

git branch --list "feature-*"

Lister à la fois les branches de suivi distantes et les branches locales. Affiche toutes les branches qui existent en local et toutes les branches distantes que votre dépôt connaît.

RecommandéVoir ensemble les branches locales et de suivi distantes après un fetch

Exemple

git branch -a

Ne lister que les branches de suivi distantes. Ce sont des références locales (refs/remotes/...) qui représentent l’état des branches des dépôts distants au moment du dernier fetch.

Si nécessaireNe liste que les branches de suivi distantes ; lancez d’abord git fetch

Exemple

git branch -r

Supprimer une branche. Elle doit être entièrement fusionnée dans sa branche upstream, ou dans HEAD si aucun upstream n’a été défini. C’est une suppression sûre qui vous protège contre la perte de travail.

RecommandéNettoyage sans risque : refuse si la branche a du travail non fusionné

Exemple

git branch -d feature-complete

Déplacer/renommer une branche avec sa configuration et son reflog. Si vous êtes sur la branche, vous pouvez omettre l’ancien nom.

RecommandéRenomme une branche et garde son reflog ; échoue sans risque si le nom existe

Exemple

git branch -m old-name new-name

Afficher le hash et le sujet de chaque branche, et son avance ou son retard sur son upstream. Utilisez -vv pour afficher aussi le nom de la branche upstream (et le chemin d’un worktree lié).

Recommandé-vv montre en un coup d’œil l’upstream et l’avance/le retard

Exemple

git branch -v

Afficher le nom de la branche courante. En HEAD détaché, rien n’est affiché. Une sortie propre, parfaite pour les scripts et l’automatisation.

Si nécessaireAffiche seulement le nom de la branche ; pratique dans les scripts et les invites

Exemple

git branch --show-current

Intermédiaire (10)

Forcer la suppression d’une branche même si elle a des modifications non fusionnées. Raccourci de --delete --force. À utiliser avec prudence : des commits peuvent devenir inaccessibles.

DéconseilléSupprime du travail non fusionné — seulement si vous êtes sûr que les commits peuvent être jetés

Exemple

git branch -D abandoned-feature

Forcer le renommage d’une branche en écrasant la cible si elle existe déjà. Raccourci de --move --force. La branche écrasée est perdue.

DéconseilléÉcrase une branche existante sans prévenir ; utilisez -m sauf si vous voulez vraiment la remplacer

Exemple

git branch -M main master

Copier une branche avec sa configuration et son reflog. Crée une nouvelle branche sur le même commit que la source. La branche d’origine est conservée (contrairement à --move).

Si nécessaireDuplique une branche avec sa configuration ; rarement utile au quotidien

Exemple

git branch -c feature feature-backup

Lister les branches dont la pointe est accessible depuis le commit indiqué (HEAD par défaut). Ces branches ont été entièrement intégrées et peuvent être supprimées sans risque avec -d.

RecommandéMontre les branches entièrement fusionnées, qu’on peut supprimer sans risque

Exemple

git branch --merged main

Ne lister que les branches dont la pointe n’est PAS accessible depuis le commit indiqué (HEAD par défaut). Ces branches contiennent du travail pas encore intégré qui demande de l’attention avant toute suppression.

Si nécessaireMontre les branches avec du travail pas encore intégré

Exemple

git branch --no-merged

Configurer la relation de suivi entre une branche locale et une branche distante. git pull/push fonctionnent alors sans préciser le dépôt distant ni la branche.

RecommandéRelie une branche à sa branche distante pour que pull et push fonctionnent tout seuls

Exemple

git branch -u origin/main

Retirer les informations de suivi de l’upstream d’une branche. Ensuite, git pull et git push demanderont d’indiquer explicitement le dépôt distant et la branche.

Si nécessaireSupprime le lien de suivi, par ex. une fois la branche distante supprimée

Exemple

git branch --unset-upstream

Créer une nouvelle branche locale qui suit une branche distante. L’upstream de la nouvelle branche est configuré automatiquement pour git pull/push.

Si nécessaireDéfinit l’upstream à la création ; déjà le comportement par défaut depuis une branche distante

Exemple

git branch --track feature origin/feature

Ne lister que les branches dont le commit de pointe descend du commit indiqué (le contient). Pratique pour savoir quelles branches ont un correctif ou une fonctionnalité précise. HEAD par défaut si aucun commit n’est indiqué.

Si nécessaireTrouve quelles branches contiennent déjà un correctif ou un commit donné

Exemple

git branch --contains a1b2c3d

Trier les branches selon la clé donnée. Préfixe - pour l’ordre décroissant. Clés courantes : committerdate, authordate, refname.

Si nécessaire--sort=-committerdate montre d’abord les branches récemment actives

Exemple

git branch --sort=-committerdate

Choisir la bonne option

Voir les branches

Différentes façons de lister et d’inspecter les branches

CommandeMontre les localesMontre les distantesInfos en plusCas d’usage
git branchOuiNoBranche courante marquée *Coup d’œil rapide aux branches locales
git branch -rNoOuiRéférences de suivi distantesVoir ce qu’il y a sur le serveur
git branch -aOuiOuiToutes les référencesVue complète de toutes les branches
git branch -vOuiNoDernier commit de chaque brancheVoir l’activité des branches d’un coup d’œil
git branch -vvOuiNoUpstream + avance/retardVérifier la synchronisation avec le dépôt distant
git branch --show-currentCourante seulementNoJuste le nomScripts, invites du shell

Supprimer des branches

Suppression sûre ou forcée - connaissez la différence

CommandeExige une fusionPeut perdre du travailQuand l’utiliser
-d (--delete)OuiNoAprès la fusion d’une PR, nettoyage de routine
-D (--delete --force)NoOuiAbandonner un travail expérimental

Renommer et copier des branches

Des options pour réorganiser les noms de vos branches

CommandeÉcrase l’existanteGarde l’originaleUsage typique
-m (--move)Non (échoue)NoRenommer : feature → feature-v2
-M (--move --force)OuiNoRemplacer un nom de branche existant
-c (--copy)Non (échoue)OuiDupliquer une branche pour expérimenter
-C (--copy --force)OuiOuiCopier, écraser si elle existe

Filtrer les branches selon leur fusion

Trouver les branches prêtes à supprimer ou encore en cours

CommandeMontreButSuite habituelle
--mergedBranches fusionnées dans HEADTrouver les candidates au nettoyagegit branch -d <branch>
--merged mainBranches fusionnées dans mainTrouver les branches qu’on peut supprimer sans risqueSupprimer en masse les branches fusionnées
--no-mergedBranches NON fusionnéesTrouver le travail en coursRelire avant une release
--contains <commit>Branches contenant un commitSavoir où est parti un correctifVérifier le déploiement d’un hotfix

Suivi de l’upstream

Configurer la relation entre branches locales et distantes

CommandeActionEffetQuand l’utiliser
-u origin/mainDéfinir l’upstreamgit push/pull fonctionnent sans argumentsAprès avoir créé une branche locale
--track origin/featureCréer + définir l’upstreamNouvelle branche locale qui suit une distanteCommencer à travailler sur une branche distante
--unset-upstreamRetirer l’upstreamSe déconnecter du dépôt distantArrêter de suivre une branche distante supprimée

Exemples de workflows

1
git branch feature-login

Créer une nouvelle branche pour la fonctionnalité

2
git switch feature-login

Passer sur la nouvelle branche

3
(make changes and commits)

Travailler sur la fonctionnalité en plusieurs commits

4
git switch main && git merge feature-login

Fusionner la fonctionnalité terminée dans main

5
git branch -d feature-login

Supprimer la branche de fonctionnalité après la fusion

1
git branch --merged

Lister les branches déjà fusionnées

2
git branch -d branch-name

Supprimer sans risque les branches fusionnées une par une

3
git fetch --prune

Retirer les références de suivi distantes périmées

4
git branch -r

Vérifier que les branches distantes sont propres

1
git fetch origin

Récupérer les dernières infos sur les branches distantes

2
git branch -r

Lister les branches distantes disponibles

3
git branch --track feature origin/feature

Créer une branche locale qui suit la distante

4
git switch feature

Passer sur la nouvelle branche de suivi

1
git branch -m old-name new-name

Renommer la branche locale

2
git push origin -u new-name

Pousser le nouveau nom de branche vers le dépôt distant

3
git push origin --delete old-name

Supprimer l’ancien nom de branche du dépôt distant

1
git log --oneline -1

Récupérer le hash du commit recherché

2
git branch --contains <commit-hash>

Trouver les branches locales qui contiennent ce commit

3
git branch -r --contains <commit-hash>

Trouver les branches distantes qui contiennent ce commit

Dépannage

Impossible de supprimer la branche - pas entièrement fusionnée

Cause : La branche a des commits non fusionnés dans son upstream (ou dans HEAD si elle n’a pas d’upstream)

Fusionnez d’abord la branche, ou utilisez -D pour forcer la suppression si vous êtes sûr de vouloir jeter ce travail

git branch -D branch-name

Impossible de supprimer la branche courante

Cause : Vous essayez de supprimer la branche sur laquelle vous êtes

Passez d’abord sur une autre branche, puis supprimez la branche visée

git switch main && git branch -d old-branch

Ce nom de branche existe déjà

Cause : Vous essayez de créer une branche avec un nom qui existe déjà

Choisissez un autre nom, supprimez d’abord la branche existante, ou utilisez -f pour la replacer sur un nouveau point de départ

git branch -f existing-name <start-point>

Aucun upstream configuré pour le push

Cause : La branche locale n’a pas de relation de suivi avec une branche distante

Configurer la relation de suivi avec l’upstream

git push -u origin branch-name

La branche distante n’apparaît pas dans git branch -r

Cause : Le dépôt local n’a pas les dernières infos sur les branches distantes

Faites un fetch depuis le dépôt distant pour mettre à jour vos branches de suivi distantes

git fetch origin

HEAD détaché après un checkout

Cause : Vous avez extrait un commit directement au lieu d’une branche

Créez une nouvelle branche sur le commit courant, ou revenez sur une branche existante

git switch -c new-branch-name

La branche suit le mauvais dépôt distant

Cause : L’upstream est configuré pour suivre une mauvaise branche distante

Redéfinissez le suivi de l’upstream vers la bonne branche distante

git branch -u origin/correct-branch

Impossible de voir toutes les branches

Cause : Seules les branches locales sont affichées par défaut

Utilisez l’option -a pour afficher à la fois les branches locales et de suivi distantes

git branch -a

Astuces et pièges

Bonnes pratiques

  • ✓Utilisez des noms de branche descriptifs qui indiquent leur but : feature/user-auth, bugfix/login-error, hotfix/security-patch
  • ✓Supprimez les branches après la fusion pour garder le dépôt propre - utilisez 'git branch --merged' pour trouver celles qu’on peut supprimer sans risque
  • ✓Créez toujours les branches de fonctionnalité depuis une branche main à jour pour limiter les conflits de fusion
  • ✓Utilisez 'git branch -vv' pour voir les relations de suivi et l’avance/le retard
  • ✓Configurez le suivi en créant les branches avec 'git push -u origin branch-name' pour simplifier push et pull
  • ✓Évitez de travailler directement sur main/master - créez toujours une branche pour vos modifications
  • ✓Utilisez 'git branch --no-merged' pour trouver les branches dont le travail est encore en cours
  • ✓Synchronisez régulièrement les branches distantes avec 'git fetch --prune' pour retirer les références périmées
  • ✓Pensez à utiliser 'git switch' plutôt que 'git checkout' pour une intention plus claire quand vous changez de branche
  • ✓Utilisez '--sort=-committerdate' pour voir d’abord les branches les plus récemment actives
  • ✓Avant de supprimer une branche avec -D, vérifiez que vous n’en avez plus besoin avec 'git log branch-name'
  • ✓Écrivez les noms de branche en minuscules avec des tirets, pour la cohérence et la compatibilité

Erreurs fréquentes

  • ✗S’attendre à ce que 'git branch <name>' bascule sur la nouvelle branche. Elle ne fait que la créer - utilisez 'git switch <name>' ou 'git checkout -b <name>' pour la créer et y basculer.
  • ✗Essayer de supprimer la branche courante. Il faut d’abord passer sur une autre branche avant de supprimer celle où vous êtes.
  • ✗Utiliser -d sur des branches non fusionnées et perdre du travail. L’option -d vous protège - si vous voulez vraiment supprimer du travail non fusionné, utilisez -D.
  • ✗Oublier de pousser les nouvelles branches vers le dépôt distant. Les branches locales ne sont pas partagées tant que vous n’avez pas fait 'git push -u origin <branch>'.
  • ✗Ne pas faire le ménage dans les anciennes branches. Utilisez régulièrement 'git branch --merged' pour trouver et supprimer les branches déjà fusionnées.

FAQ

A:

'git branch <name>' crée seulement une nouvelle branche sans y basculer. 'git checkout -b <name>' crée une nouvelle branche ET y bascule en une seule commande. L’équivalent moderne est 'git switch -c <name>'.

A:

Utilisez 'git branch -m old-name new-name' pour renommer une branche. Si vous êtes sur la branche à renommer, 'git branch -m new-name' suffit. Pour les branches distantes, il faut pousser le nouveau nom et supprimer l’ancien.

A:

-d est une suppression sûre qui ne fonctionne que si la branche est entièrement fusionnée dans son upstream (ou dans HEAD si aucun upstream n’est défini). -D est une suppression forcée qui retire la branche quel que soit son état de fusion. N’utilisez -D que si vous êtes sûr de vouloir jeter des commits non fusionnés.

A:

Utilisez 'git push origin --delete branch-name' ou la syntaxe plus courte 'git push origin :branch-name'. Cela retire la branche du dépôt distant.

A:

Les branches de suivi distantes (comme origin/main) sont des références locales qui suivent l’état des branches des dépôts distants. Elles sont mises à jour lors d’un fetch ou d’un pull et montrent où pointent les branches distantes.

A:

Utilisez 'git branch --show-current' pour avoir juste le nom, ou 'git branch' pour voir toutes les branches avec la courante marquée d’un *. 'git status' affiche aussi la branche courante.

A:

Git ne permet pas de supprimer la branche sur laquelle vous êtes. Passez d’abord sur une autre branche avec 'git switch other-branch', puis supprimez la branche visée.

A:

Utilisez 'git branch branch-name commit-hash' pour créer une branche à partir de n’importe quel commit. Le point de départ peut être un hash de commit, un tag ou un autre nom de branche.

A:

La branche upstream (ou de suivi) est la branche distante vers laquelle votre branche locale pousse et depuis laquelle elle tire par défaut. Définissez-la avec 'git branch -u origin/branch-name' ou 'git push -u origin branch-name'.

A:

Utilisez 'git branch --sort=-committerdate' pour lister d’abord les branches qui ont reçu les commits les plus récents. Ajoutez -v pour voir aussi le hash et le message du commit.