Git

git-branch last updated in 2.51.0

NOM

git-branch - Liste, crée, ou supprime des branches

SYNOPSIS

git branch [--color[=<when>] | --no-color] [--show-current]
	   [-v [--abbrev=<n> | --no-abbrev]]
	   [--column[=<options>] | --no-column] [--sort=<clé>]
	   [--merged [<commit>]] [--no-merged) [<commit>]]
	   [--contains [<commit>]] [--no-contains [<commit>]]
	   [--points-at <objet>] [--format=<format>]
	   [(-r | --remotes) | (-a | --all)]
	   [--list] [<motif>…]
git branch [--track[=(direct|inherit)] | --no-track] [-f]
	   [--recurse-submodules] <nom-de-branche> [<point-de-départ>]
git branch (--set-upstream-to=<amont> | -u <amont>) [<nom-de-branche>]
git branch --unset-upstream [<nom-de-branche>]
git branch (-m | -M) [<ancienne-branche>] <nouvelle-branche>
git branch (-c | -C) [<ancienne-branche>] <nouvelle-branche>
git branch (-d | -D) [-r] <nom-de-branche>…
git branch --edit-description [<nom-de-branche>]

DESCRIPTION

Si --list est donné, ou s’il n’y a pas d’arguments sans option, les branches existantes sont listées ; la branche actuelle sera surlignée en vert et marquée d’un astérisque. Toutes les branches extraites dans les arbres de travail liés seront mis en évidence en cyan et marqués d’un signe plus. L’option -r ajoute la liste des branches de suivi à distance et l’option`-a` affiche les branches locales et distantes.

Si un <motif> est donné, il est utilisé comme joker du shell pour restreindre la sortie aux branches correspondantes. Si plusieurs motifs sont donnés, une branche est affichée si elle correspond à l’un des motifs.

Notez que lorsque vous fournissez un <motif> , vous devez utiliser --list ; sinon, la commande peut être interprétée comme une création de branche.

Avec --contains, montrer seulement les branches qui contiennent le commit indiqué (en d’autres termes, les branches dont les commits sommets sont des descendants du commit indiqué), avec --no-contains inverser. Avec --merged, seules les branches fusionnées dans le commit indiqué (c’est-à-dire les branches dont les commits sommets sont accessibles depuis le commit indiqué) seront listées. Avec --no-merged, seules les branches non fusionnées dans le commit indiqué seront listées. Si l’argument <commit> est manquant, il prend par défaut la valeur HEAD (c’est-à-dire le sommet de la branche courante).

La deuxième forme de la commande crée une nouvelle tête de branche nommée <nom-de-branche> qui pointe vers la HEAD actuelle, ou <point-de-départ> si elle est fournie. Dans un cas particulier, pour le <point-de-départ>, vous pouvez utiliser <rev-a>...<rev-b> comme raccourci pour la base de fusion de <rev-a> et <rev-b> s’il y a exactement une base de fusion. Vous pouvez omettre tout au plus un des <rev-a> et <rev-b>, auquel cas il s’agit par défaut de HEAD.

Notez que cela créera la nouvelle branche, mais ne fera pas passer l’arbre de travail sur celle-ci ; utilisez git switch <nouvelle-branche> pour passer sur la nouvelle branche.

Lorsqu’une branche locale est démarrée à partir d’une branche de suivi à distance, Git configure la branche (plus précisément les entrées de configuration branch.<nom>.remote et branch.<nom>.merge) de façon à ce que git pull fusionne correctement avec la branche de suivi à distance. Ce comportement peut être modifié via le drapeau de configuration global branch.autoSetupMerge. Ce paramètre peut être modifié en utilisant les options --track et --no-track, et changé plus tard en utilisant git branch --set-upstream-to.

Avec une option -m ou -M, <ancienne-branche> sera renommée en <nouvelle-branche>. Si <ancienne-branche> avait un reflog correspondant, il est renommé pour correspondre à <nouvelle-branche>, et une entrée de reflog est créée pour se souvenir du renommage de la branche. Si <nouvelle-branche> existe déjà, -M doit être utilisé pour forcer le changement de nom.

Les options -c et -C ont exactement la même sémantique que -m et -M, sauf qu’au lieu de renommer la branche,elle sera copiée sous un nouveau nom avec sa configuration et son reflog.

Avec une option -d ou -D, <nom-de-branche> sera supprimé. Vous pouvez spécifier plus d’une branche pour la suppression. Si la branche a actuellement un reflog, alors le reflog sera aussi supprimé.

Utilisez -r avec -d pour supprimer les branches de suivi à distance. Notez qu’il est logique de supprimer les branches de suivi à distance uniquement si elles n’existent plus dans le dépôt distant ou si git fetch a été configuré pour ne pas les récupérer à nouveau. Voir aussi la sous-commande prune de git-remote[1] pour une méthode de nettoyage toutes les branches obsolètes de suivi à distance.

OPTIONS

-d
--delete: Supprimer une branche. La branche doit être entièrement fusionnée dans sa branche amont, ou dans HEAD si aucune branche amont n’a été fixée avec --track ou --set-upstream-to.
-D: Raccourci pour --delete --force.
--create-reflog: Créer le reflog de la branche. Cela active l’enregistrement de toutes les modifications apportées à la branche ref, permettant l’utilisation d’expressions sha1 basées sur la date telles que <nom-de-branche>@\{yesterday}. Notez que dans les dépôts non-nus, les reflogs sont généralement activés par défaut par l’option de configuration core.logAllRefUpdates. La forme négative --no-create-reflog ne fait que remplacer un --create-reflog précédent, mais n’annule pas actuellement le paramètre core.logAllRefUpdates.
-f
--force: Réinitialiser <branche> à <point-de-départ>, même si <branche> existe déjà. Sans -f, git branch refuse de changer une branche existante. En combinaison avec -d (ou --delete), permettre la suppression de la branche indépendamment de son statut de fusion, ou si elle pointe même sur un commit valide. En combinaison avec -m (ou --move), il est possible de renommer la branche même si le nouveau nom de la branche existe déjà, il en va de même pour -c (ou --copy).

Notez que git branch -f <branche> [<point-de-départ>], même avec -f, refuse de modifier une branche existante <branche> qui est extraite dans un autre arbre-de-travail lié au même dépôt.
-m
--move: Déplacer/renommer une branche ainsi que sa config et son reflog .
-M: Raccourci pour --move --force.
-c
--copy: Copier une branche, ainsi que sa config et son reflog.
-C: Raccourci pour --copy --force.
--color[=<quand>]: Colorier les branches pour mettre en évidence les branches actuelles, locales et de suivi à distance. La valeur doit être always (c-à-d toujours) (valeur par défaut), never (c-à-d jamais) ou auto.
--no-color: Désactiver les couleurs des branches, même lorsque le fichier de configuration donne la sortie en couleur par défaut. Même chose que --color=never.
-i
--ignore-case: Le tri et le filtrage de branches sont non-sensibles à la casse.
--omit-empty: Ne pas afficher de nouvelle ligne après les refs formatés lorsque le format se développe en chaîne vide.
--column[=<options>]
--no-column: Afficher la liste des branches en colonnes. Voir la variable de configuration column.branch pour la syntaxe des options.--column et --no-column sans options équivalent respectivement à always et never.

Cette option ne s’applique qu’en mode non verbeux.
--sort=<clé>: Trier en fonction de la <clé> donnée. Préfixer par - pour trier par ordre décroissant de la valeur. Vous pouvez utiliser l’option --sort=<clé> plusieurs fois, auquel cas la dernière clé devient la clé primaire. Les clés supportées sont les mêmes que celles de git-for-each-ref[1]. L’ordre de tri est par défaut la valeur configurée pour la variable branch.sort si elle existe, ou le tri basé sur le nom de référence complet (y compris le préfixe refs/...). Cela liste d’abord les HEAD détachées (si présentes), puis les branches locales et enfin les branches de suivi à distance. Voir git-config[1].
-r
--remotes: Énumérer ou supprimer (si utilisé avec -d) les branches de suivi à distance. Combiner avec --list pour faire correspondre le(s) motif(s) optionnel(s).
-a
--all: Afficher à la fois les branches de suivi et les branches locales. Combiner avec --list pour faire correspondre un ou des motifs optionnels.
-l
--list: Listes les branches. Avec l’option <pattern>..., par exemple git branch --list maint-*', ne lister que les branches qui correspondent au(x) motif(s).
--show-current: Afficher le nom de la branche actuelle. En état de HEAD détachée, rien n’est affiché.
-v
-vv
--verbose: En mode liste, afficher le sha1 et valider le sujet pour chaque tête, ainsi que la relation avec la branche amont (le cas échéant). S’il est donné deux fois, imprimer le chemin de l’arbre de travail lié (le cas échéant) ainsi que le nom de la branche amont (voir aussi git remote show <remote>). Notez que la HEAD de l’arbre de travail actuel n’aura pas son chemin d’accès affiché (il s’agira toujours de votre répertoire actuel).
-q
--quiet: Être plus discret lors de la création ou la destruction d’une branche, en supprimant les messages qui ne sont pas des erreurs.
--abbrev=<n>: Dans la liste détaillée qui indique le nom de l’objet commit, indiquer le préfixe le plus court d’au moins <n> chiffres hexadécimaux, qui renvoie de manière unique à l’objet. La valeur par défaut est 7 et peut être remplacée par l’option de configuration core.abbrev.
--no-abbrev: Afficher les sha1s complets dans la liste des résultats plutôt que de les abréger.
-t
--track[=(direct|inherit)]: Lors de la création d’une nouvelle branche, configurer les entrées de configuration branch.<nom>.remote et branch.<nom>.merge pour pour définir la configuration du suivi "amont" de la nouvelle branche. Cette configuration indiquera à git de montrer la relation entre les deux branches dans "git status" et "git branch -v". En outre, il règle git pull sans arguments de tirer depuis l’amont lorsque la nouvelle branche est extraite.

La branche amont exacte est choisie en fonction de l’argument optionnel : -t, --track ou --track=direct signifie utiliser la branche du point de départ elle-même comme amont ; --track=inherit signifie copier la configuration amont de la branche du point de départ.

La variable de configuration branch.autoSetupMerge spécifie comment git switch, git checkout et git branch doivent se comporter lorsque ni --track ni --no-track ne sont spécifiés :

L’option par défaut, true, se comporte comme si --track=direct était donné lorsque le point de départ est une branche de suivi à distance. L’option false se comporte comme si --no-track était donné. always se comporte comme si --track=direct était donné. inherit se comporte comme si --track=inherit était donné. simple se comporte comme si --track=direct était donné uniquement lorsque <point-de-départ> est une branche de suivi à distance et que la nouvelle branche a le même nom que la branche distante.

Voir git-pull[1] et git-config[1] pour des discussions supplémentaires sur la façon dont les options branch.<nom>.remote et branch.<nom>.merge sont utilisées.
--no-track: Ne pas renseigner la configuration « amont », même si la configuration branch.autoSetupMerge est paramétrée.
--recurse-submodules: CETTE OPTION EST EXPÉRIMENTALE ! Fait en sorte que la commande courante fasse une récursion dans les sous-modules si submodule.propagateBranches est activé. Voir submodule.propagateBranches dans git-config[1]. Actuellement, seule la création de branches est supportée.

Lorsqu’utilisé dans la création de branche, une nouvelle branche <nom-de-branche> sera créée dans le superprojet et tous les sous-modules au <point-de-départ> du superprojet. Dans les sous-modules, la branche pointera vers le commit du sous-module au <point-de-départ> du superprojet, mais les informations de suivi de la branche seront établies en fonction des branches et des distants du sous-module, par ex. git branch --recurse-submodules topic origin/main créera la branche du sous-module "topic" qui pointe vers le commit du sous-module dans le "origin/main" du superprojet, mais suivra le "origin/main" du sous-module.
--set-upstream: Comme cette option avait une syntaxe confuse, elle n’est plus supportée. Veuillez utiliser --track ou --set-upstream-to à la place.
-u <amont>
--set-upstream-to=<amont>: Configurer les informations de suivi de <nom-de-branche> pour que <amont> soit considéré comme la branche amont de <nom-de-branche>. Si aucun <nom-de-branche> n’est spécifié, alors la branche actuelle est utilisée par défaut.
--unset-upstream: Supprimer les informations en amont pour <nom-de-branche>. Si aucune branche n’est spécifiée, la branche actuelle est utilisée par défaut.
--edit-description: Ouvrir un éditeur et éditer le texte pour expliquer à quoi sert la branche, qui sera utilisée par diverses autres commandes (par exemple format-patch, pull-request et merge (si activé)). Des explications sur plusieurs lignes peuvent être utilisées.
--contains [<commit>]: N’indiquer que les branches qui contiennent le commit spécifié (HEAD si non spécifié). Implique --list.
--no-contains [<commit>]: N’indiquer que les branches qui ne contiennent pas <commit> (HEAD si non spécifié). Implique --list.
--merged [<commit>]: N’indiquer que les branches dont les sommets sont accessibles depuis <commit> (HEAD si non spécifié). Implique --list.
--no-merged [<commit>]: N’indiquer que les branches dont les sommets ne sont pas accessibles depuis le <commit> (HEAD si non spécifié). Implique --list.
--points-at <objet>: N’indiquer que les branches de <objet>.
--format <format>: Une chaîne qui interpole %(fieldname) à partir d’une référence de branche montrée et l’objet vers lequel elle pointe. <format> est le même que celui de git-for-each-ref[1].
<nom-de-branche>: Le nom de la branche à créer ou à supprimer. Le nouveau nom de la branche doit passer tous les contrôles définis par git-check-ref-format[1]. Certains de ces contrôles peuvent restreindre les caractères autorisés dans un nom de branche.
<point_de_départ>: La nouvelle tête de branche pointera sur ce commit. Il peut être donné sous la forme d’un nom de branche, d’un id de commit ou d’une étiquette. Si cette option est omise, la HEAD actuelle sera utilisée à la place.
<ancienne-branche>: La nom d’une branche existante. Si cette option est omise, le nom de la branche actuelle sera utilisée à la place.
<nouvelle-branche>: Le nouveau nom d’une branche existante. Les mêmes restrictions que pour <nom-de-branche> s’appliquent.

CONFIGURATION

Le terme pager.branch n’est respecté que lorsqu’il s’agit d’énumérer des branches, c’est-à-dire lorsque --list est utilisé ou sous-entendu. La valeur par défaut est d’utiliser un pager. Voir git-config[1].

Tout ce qui se trouve au-dessus de cette ligne dans cette section n’est pas inclus dans la documentation git-config[1]. Le contenu qui suit est le même que celui qui s’y trouve :

Warning

Missing fr/config/branch.adoc

See original version for this content.

EXEMPLES

Démarrer le développement à partir d’une étiquette connue

$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
$ cd my2.6
$ git branch my2.6.14 v2.6.14   (1)
$ git switch my2.6.14

Cette étape et la suivante pourraient être combinées en une seule étape avec "checkout -b my2.6.14 v2.6.14".

Supprimer une branche inutile

$ git clone git://git.kernel.org/.../git.git my.git
$ cd my.git
$ git branch -d -r origin/todo origin/html origin/man   (1)
$ git branch -D test                                    (2)

Supprimer les branches de suivi à distance "todo", "html" et "man". La prochaine opération git fetch ou git pull les créera à nouveau, à moins que vous ne les configuriez autrement. Voir git-fetch[1].
Supprimer la branche "test" même si la branche "master" (ou n’importe quelle branche actuellement extraite) n’a pas tous les commits de la branche test.

Lister les branches d’un distant spécifique

$ git branch -r -l '<distant>/<motif>'                 (1)
$ git for-each-ref 'refs/remotes/<distant>/<motif>'    (2)

L’utilisation de -a associerait <distant> avec toutes les branches locales dont le préfixe correspond au motif <distant>.
for-each-ref accepte un large éventail d’options. Voir git-for-each-ref[1]

Les motifs devront normalement être cités.

NOTES

Si vous créez une branche sur laquelle vous voulez passer immédiatement, il est plus facile d’utiliser la commande git switch avec son option -c pour faire la même chose avec une seule commande.

Les options --contains, --no-contains, --merged et --no-merged servent quatre objectifs connexes mais différents :

--contains <commit> est utilisé pour trouver toutes les branches qui devront faire l’objet d’une attention particulière si <commit> devait être rebasé ou modifié, puisque ces branches contiennent le <commit> spécifié.
--no-contains <commit> est l’inverse de cela, c’est-à-dire les branches qui ne contiennent pas le <commit> spécifié.
--merged est utilisé pour trouver toutes les branches qui peuvent être supprimées en toute sécurité, puisque ces branches sont entièrement contenues par HEAD.
--no-merged est utilisé pour trouver les branches qui sont candidates à la fusion avec HEAD, puisque ces branches ne sont pas entièrement contenues par HEAD.

Lorsque vous combinez plusieurs filtres --contains et --no-contains, seules les références qui contiennent au moins un des commits --contains et ne contiennent aucun des commits --no-contains sont affichées.

Lorsque vous combinez plusieurs filtres --merged et --no-merged, seules les références qui sont accessibles depuis au moins un des commits --merged et depuis aucun des commits --no-merged sont affichées.

VOIR AUSSI

git-check-ref-format[1], git-fetch[1], git-remote[1], « Comprendre l’historique : Qu’est-ce qu’une branche ?' » dans le manuel d’utilisateur Git.

Fait partie de la suite git[1]

TRADUCTION

Cette page de manuel a été traduite par Jean-Noël Avila <jn.avila AT free DOT fr> et les membres du projet git-manpages-l10n. Veuillez signaler toute erreur de traduction par un rapport de bogue sur le site https://github.com/jnavila/git-manpages-l10n .

Setup and Config

Getting and Creating Projects

Basic Snapshotting

Branching and Merging

Sharing and Updating Projects

Inspection and Comparison

Patching

Debugging

Email

External Systems

Server Admin

Guides

Administration

Plumbing Commands

NOM