Git

git-checkout last updated in 2.44.0

NOM

git-checkout - Bascule sur une autre branche ou restaure des fichiers de l’arbre de travail

SYNOPSIS

git checkout [-q] [-f] [-m] [<branche>]
git checkout [-q] [-f] [-m] --detach [<branche>]
git checkout [-q] [-f] [-m] [--detach] <commit>
git checkout [-q] [-f] [-m] [[-b|-B|--orphan] <nouvelle-branche>] [<point-de-départ>]
git checkout [-f] <arbre-esque> [--] <spec-de-chemin>…
git checkout [-f] <arbre-esque> --pathspec-from-file=<fichier> [--pathspec-file-nul]
git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [--] <spec-de-chemin>…
git checkout [-f|--ours|--theirs|-m|--conflict=<style>] --pathspec-from-file=<fichier> [--pathspec-file-nul]
 git checkout (-p|--patch) [<arbre-esque>] [--] [<spec-de-chemin>…]

DESCRIPTION

Met à jour les fichiers dans l’arbre de travail pour correspondre à la version dans l’index ou dans l’arbre spécifié. Si aucun spécificateur de chemin n’est fourni, git checkout met aussi à jour HEAD pour positionner la branche spécifiée comme la branche actuelle.

git checkout [<branche>]

Pour se préparer à travailler sur <branche>, basculer dessus en mettant l’index et les fichiers de l’arbre de travail à jour, et en pointant HEAD sur cette branche. Les modifications locales aux fichiers de l’arbre de travail sont conservées, de sorte qu’elles peuvent être validées sur la <branche>.

Si la <branche> n’est pas trouvée mais qu’il existe une branche de suivi pour un dépôt distant unique (appelée <distant>) avec un nom correspondant et --no-guess n’est pas spécifié, le traiter comme équivalent à

$ git checkout -b <branche> --track <distant>/<branche>

Vous pourriez omettre <branche>, auquel cas la commande dégénère en « extraire la branche actuelle », qui est une opération nulle de luxe avec des effets de bord plutôt chers de ne montrer que l’information de suivi, si elle existe, pour la branche actuelle.

git checkout -b|-B <nouvelle-branche> [<point-de-départ>]

Spécifier -b provoque la création d’une nouvelle branche comme si git-branch[1] était lancé puis la branche extraite. Dans ce cas, vous pouvez utiliser les options --track ou --no-track, qui seront passées à git branch. Pour plus de confort, --track sans -b implique la création d’une branche ; voir la description de --track ci-dessous.

Si -B est fourni, <nouvelle-branche> est créée si elle n’existe pas ; sinon, elle est réinitialisée. C’est l’équivalent transactionnel de

$ git branch -f <branche> [<point-de-départ>]
$ git checkout <branche>

c’est-à-dire que la branche n’est pas réinitialisée/créée à moins que "git checkout" soit réussi (par exemple, lorsque la branche est utilisée dans un autre arbre de travail, pas seulement que la branche actuelle reste la même, mais la branche n’est pas réinitialisée au point de départ non plus).

git checkout --detach [<branche>]

git checkout [--detach] <commit>

Prépare à travailler par-dessus <commit>, en détachant HEAD dessus (voir la section « HEAD DÉTACHÉE »), et en mettant l’index et les fichiers de l’arbre de travail à jour. Les modifications locales des fichiers dans l’arbre de travail sont conservées, de sorte que l’arbre de travail sera le résultat du commit plus les modifications locales.

Quand l’argument <commit> est un nom de branche, l’option --detach peut être utilisée pour détacher HEAD au sommet de la branche (git checkout <branche> extrairait cette branche sans détacher HEAD).

Omettre <branche> détache HEAD au sommet de la branche actuelle.

git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<arbre-esque>] [--] <spéc. de chemin>…

git checkout [-f|--ours|--theirs|-m|--conflict=<style>] [<arbre-esque>] --pathspec-from-file=<fichier> [--pathspec-file-nul]

Écraser le contenu des fichiers qui correspondent au spécificateur-de-chemin. Lorsque le <arbre-esque> (le plus souvent un commit) n’est pas donné, écraser l’arbre de travail avec le contenu de l’index. Lorsque le <arbre-esque> est donné, écraser à la fois l’index et l’arbre de travail avec le contenu du <arbre-esque>.

L’index peut contenir des entrées non fusionnées à cause d’un échec précédent de fusion. Par défaut, si vous essayez d’extraire une telle entrée depuis l’index, l’opération d’extraction échouera et rien ne sera extrait. L’utilisation de -f forcera à ignorer ces entrées non fusionnées. Le contenu depuis un côté donné de la fusion peut être extrait de l’index en utilisant --ours (notre côté) ou --theirs (l’autre côté). Avec -m, les modifications opérées sur le fichier de l’arbre de travail peuvent être jetées pour récréer le résultat originel de conflit de fusion.

git checkout (-p|--patch) [<arbre-esque>] [--] [<spéc. de chemin>…]

C’est similaire au mode précédent, mais vous laisse utiliser l’interface interactive pour afficher la sortie « diff » et choisir quelles sections utiliser dans le résultat. Voir plus bas la description de l’option --patch.

OPTIONS

-q

--quiet

Silencieux, supprimer les messages d’état.

--progress

--no-progress

L’état d’avancement est affiché sur la sortie standard d’erreur par défaut quand elle est attachée à un terminal, à moins que --quiet ne soit spécifié. Cette bascule active l’état d’avancement même sans être attaché à un terminal, indépendamment de --quiet.

-f

--force

Lors du basculement de branche, continuer même si l’index ou l’arbre de travail sont différents de HEAD, et même s’il y a des fichiers non-suivis qui bloquent.Ceci peut servir à éliminer des modifications locales ainsi que tous les fichiers ou répertoires non-suivis qui gênent.

Lors de l’extraction de chemins depuis l’index, ne pas échouer sur des entrées non fusionnées ; à la place, les entrées non fusionnées sont ignorées.

--ours

--theirs

Lors de l’extraction de chemins depuis l’index, extraire l’état #2 (ours, le nôtre) ou #3 (theirs, le leur) pour les chemins non fusionnés.

Veuillez noter que pendant git rebase et git pull --rebase, ours et theirs peuvent sembler échangés ; --ours fournit la version depuis la branche sur laquelle les modifications sont rebasées, tandis que --theirs fournit la version de la branche qui contient le travail rebasé.

C’est parce que rebase est utilisé dans une approche qui traite l’historique distant comme la référence canonique partagée, et traite le travail sur la branche que vous rebasez comme un travail tiers à intégrer, et vous endossez temporairement le rôle du gardien de l’historique canonique quand vous rebasez. En tant que gardien de l’historique canonique, vous devez voir l’historique distant comme le vôtre (ours, c’est-à-dire « notre historique partagé canonique »), tandis que votre travail sur l’autre branche devient le tiers (theirs, c’est-à-dire « le travail d’un contributeur sur le canonique »).

-b <nouvelle-branche>

Créer une nouvelle branche nommée <nouvelle-branche>, la commencer à <point-de-départ> et extraire la branche résultante ; voir git-branch[1] pour plus de détails.

-B <nouvelle-branche>

Créer la branche <nouvelle-branche>, la commencer à <point-de-départ> et l’extraire ; si elle existe déjà, alors la réinitialise à <point-de-départ>. C’est équivalent à lancer git branch avec -f suivi de git checkout de cette branche ; voir git-branch[1] pour plus de détails.

-t

--track[=(direct|inherit)]

À la création d’une nouvelle branche, établir la configuration upstream (branche amont). Voir --track dans git-branch[1] pour plus de détails.

Si aucune option -b n’est fournie, le nom de la nouvelle branche sera dérivé de la branche de suivi à distance, en regardant la partie locale de la spécification de référence configurée pour le distant correspondant et en enlevant la partie initiale jusqu’au "*". Cela indiquerait d’utiliser le nom « hack » comme branche locale créée à partir de origin/hack (ou remotes/origin/hack, ou même refs/remotes/origin/hack). Si le nom fourni ne contient pas de barre oblique, ou si le résultat de la dérivation est un nom vide, la dérivation échoue. Vous pouvez spécifier explicitement un nom avec -b dans ce cas.

--no-track

Ne pas renseigner la configuration « amont », même si la configuration branch.autoSetupMerge est true.

--guess

--no-guess

Si la <branche> n’est pas trouvée mais qu’il existe une branche de suivi pour un dépôt distant unique (appelé <distant>) avec un nom correspondant, le traiter comme équivalent à

$ git checkout -b <branche> --track <distant>/<branche>

Si la branche existe dans plus d’un distant et que l’un d’entre eux est la valeur de la variable de configuration checkout.defaultRemote, celui-ci sera utilisé pour désambiguïser, même si la <branche> n’est pas unique parmi tous les distants. Réglez la variable checkout.defaultRemote=origin par exemple pour extraire toujours les branches distantes depuis celle-ci si <branche> est ambigüe mais existe sur le distant origin. Voir aussi checkout.defaultRemote dans git-config[1].

--guess est le comportement par défaut. Utilisez --no-guess pour le désactiver.

Le comportement par défaut peut être défini via la variable de configuration checkout.guess.

-l

Créer le reflog de la nouvelle branche ; voir git-branch[1] pour plus de détails.

-d

--detach

Plutôt que d’extraire une branche pour travailler dessus, extraire un commit pour l’inspecter et faire des expériences jetables. C’est le comportement par défaut de git checkout <commit> quand <commit> n’est pas un nom de branche. Voir la section « HEAD DÉTACHÉE » plus bas pour plus de détails.

--orphan <nouvelle-branche>

Créer une nouvelle branche non née, nommée <nouvelle-branche>, commençant depuis <point-de-départ> et basculer dessus. Le premier commit réalisé sur cette branche n’aura pas de parent et il sera la racine du nouvel historique totalement déconnecté de toutes les autres branches et des autres commits.

L’index et l’arbre de travail sont ajustés comme si vous aviez déjà lancé git checkout <point-de-départ>. Cela vous permet de démarrer un nouvel historique qui enregistre un ensemble de chemins similaires à <point-de-départ> en lançant simplement git commit -a pour créer le commit racine.

Ceci peut être utile quand vous souhaitez publier un arbre depuis un commit sans exposer tout son historique. Vous pourriez souhaiter le faire pour publier une branche open source d’un projet dont l’arbre présent est « propre », mais dont l’historique complet contient des morceaux de code propriétaire ou autrement non publiables.

Si vous voulez démarrer un historique déconnecté qui enregistre un ensemble de chemins qui sont totalement différents de celui de <point-de-départ>, vous devriez effacer l’index et l’arbre de travail juste après avoir créé la branche orpheline en lançant git rm -rf . depuis la racine de l’arbre de travail. Après, vous pourrez préparer vos nouveaux fichiers, pour repeupler l’arbre de travail, en les copiant depuis un autre endroit, en les extrayant depuis une archive, etc.

--ignore-skip-worktree-bits

En mode d’extraction clairsemé, git checkout -- <chemins> mettrait seulement à jour les entrées correspondant à <chemins> et aux motifs clairsemés dans $GIT_DIR/info/sparse-checkout. Cette option ignore les motifs clairsemés et ré-ajoute tous les fichiers de <chemins>.

-m

--merge

Lors d’un basculement de branche, si vous avez des modifications locales sur un fichier ou plus qui sont différentes entre la branche actuelle et celle sur laquelle vous basculez, la commande refuse le basculement pour préserver vos modifications dans leur contexte. Cependant, avec cette option, une fusion à trois points entre la branche actuelle, le contenu de votre arbre de travail et la nouvelle branche est opérée et vous serez sur la nouvelle branche.

Quand un conflit de fusion apparaît, les entrées d’index pour les chemins en conflit sont laissées non-fusionnées et vous devez résoudre les conflits et les marquer résolus pour les chemins concernés avec git add (ou git rm si la fusion doit aboutir à la suppression du chemin).

Lors de l’extraction de chemins depuis l’index, cette option vous permet de récréer la fusion en conflit dans les chemins spécifiés. Cette option ne peut pas être utilisée lors de l’extraction des chemins depuis un arbre-esque.

Lors du basculement de branche avec --merge, les modifications indexées peuvent être perdues.

--conflict=<style>

Identique à l’option --merge ci-dessus, mais la manière dont les sections en conflits sont présentées est modifiée, en surchargeant la variable de configuration merge.conflictStyle. Les valeurs possibles sont merge (fusion, par défaut), diff3 et zdiff3.

-p

--patch

Sélectionner interactivement les sections dans la différence entre l'<arbre-esque> (ou l’index, si non spécifié) et l’arbre de travail. Les sections choisies sont ensuite appliquées en ordre inversé à l’arbre de travail (et si un <arbre-esque> a été spécifié, à l’index).

Ceci signifie que vous pouvez utiliser git checkout -p pour supprimer sélectivement les éditions depuis votre arbre de travail actuel. Voir la section « Mode Interactif » de git-add[1] pour apprendre à utiliser le mode --patch.

Notez que cette option utilise par défaut le mode sans superposition (voir aussi --overlay), et ne supporte pas actuellement le mode superposition.

--ignore-other-worktrees

git checkout échoue quand la référence voulue est déjà extraite dans un autre arbre de travail. Cette option force l’extraction. En d’autres termes, la réf peut être tenue par plus d’un arbre de travail.

--overwrite-ignore

--no-overwrite-ignore

Écraser silencieusement les fichiers ignorés lors du basculement de branche. C’est le comportement par défaut. Utilisez --no-overwrite-ignore pour annuler l’opération lorsque la nouvelle branche contient des fichiers ignorés.

--recurse-submodules

--no-recurse-submodules

L’utilisation de --recurse-submodules permet de mettre à jour le contenu de tous les sous-modules actifs en fonction du commit enregistré dans le super-projet. Si des modifications locales au sous-modules seraient écrasées, l’extraction échoue à moins d’utiliser -f. Si l’option n’est pas spécifiée (ou si --no-recurse-submodules est spécifié), les arbres de travail des sous-modules ne sont pas mis à jour. Comme git-submodule[1], la HEAD des sous-modules sera détachée.

--overlay

--no-overlay

Dans le mode de superposition par défaut, git checkout ne supprime jamais les fichiers de l’index ou de l’arbre de travail. Lorsque vous spécifiez --no-overlay, les fichiers qui apparaissent dans l’index et l’arbre de travail, mais pas dans «<arbre-esque>» sont supprimés, pour les faire correspondre à <arbre-esque> exactement.

--pathspec-from-file=<fichier>

Le spécificateur de chemin est passé dans <fichier> au lieu des arguments de la ligne de commande. Si <fichier> vaut - alors l’entrée standard est utilisée. Les éléments du spécificateur de chemin sont séparés par LF ou CR/LF. Les éléments du spécificateur de chemin peuvent être cités comme expliqué pour la variable de configuration core.quotePath (voir git-config[1]). Voir aussi l’option --pathspec-file-nul et l’option globale --literal-pathspecs.

--pathspec-file-nul

Uniquement significatif avec --pathspec-from-file. Les éléments du spécificateur de chemin sont séparés par le caractère NUL et tous les autres caractères sont utilisés littéralement (y compris les retours à la ligne et les guillemets).

<branche>

Branche à extraire ; si c’est une référence à une branche (c’est-à-dire un nom qui, préfixé par « refs/heads/ » est une référence valide), alors cette branche est extraite. Sinon, si c’est une référence à un commit valide, votre HEAD devient « détachée » et vous n’êtes plus sur aucune branche (voir plus bas pour plus de détails).

Vous pouvez utiliser la syntaxe @{-N} pour faire référence à la N-ième dernière branche ou commit extrait en utilisant une opération « git checkout ». Vous pouvez aussi spécifier - qui est synonyme de @{-1}.

Autre cas spécial supplémentaire, vous pouvez utiliser A...B comme raccourci pour la base de fusion de A et B s’il y a exactement une seule base de fusion. Vous pouvez ne pas spécifier A ou B, auquel cas ce sera HEAD par défaut.

<nouvelle-branche>

Nom pour une nouvelle branche.

<point_de_départ>

Le nom du commit auquel démarrer la nouvelle branche ; voir git-branch[1] pour plus de détails. HEAD par défaut.

Autre cas spécial supplémentaire, vous pouvez utiliser « A…B » comme raccourci pour la base de fusion de A et B s’il y a exactement une seule base de fusion. Vous pouvez ne pas spécifier A ou B, auquel cas ce sera HEAD par défaut.

<arbre-esque>

Arbre depuis lequel extraire (quand des chemins sont indiqués). Si non spécifié, l’index est utilisé.

--

Ne pas interpréter les arguments qui suivent comme options.

<spécificateur de chemin>…

Limite les chemins affectés par l’opération.

Pour plus de détail, voir l’entrée spécificateur de chemin dans gitglossary[7].

HEAD DÉTACHÉE

HEAD fait normalement référence à une branche nommée (par exemple, master). Dans le même temps, chaque branche pointe sur un commit spécifique. Regardons un dépôt avec trois commits, dont un est étiqueté, et avec la branche master extraite :

           HEAD (se réfère à la branche 'master')
            |
            v
a---b---c  branch 'master' (se réfère au commit 'c')
    ^
    |
  tag 'v2.0' (se réfère au commit 'b')

Quand un commit est créé dans cet état, la branche est mise à jour pour faire référence au nouveau commit. Plus précisément, git commit crée un nouveau commit d, dont le parent est le commit c, et ainsi elle met à jour la branche master pour faire référence au nouveau commit d. HEAD fait toujours référence à la branche master et donc fait maintenant référence indirectement au commit d :

$ edit; git add; git commit

               HEAD (se réfère à la branche 'master')
                |
                v
a---b---c---d  branche 'master' (se réfère au commit 'd')
    ^
    |
  tag 'v2.0' (se réfère au commit 'b')

Il est parfois utile de permettre l’extraction d’un commit qui n’est sommet d’aucune branche ou même de créer un nouveau commit qui n’est pas référencé par une branche nommée. Regardons ce qui arrive quand on extrait le commit b (ici, deux manières de faire sont montrées) :

$ git checkout v2.0  # ou
$ git checkout master^^

   HEAD (se réfère au commit 'b')
    |
    v
a---b---c---d  branch 'master' (se réfère au commit 'd')
    ^
    |
  tag 'v2.0' (se réfère au commit 'b')

Veuillez noter que quelle que soit la commande d’extraction utilisée, HEAD pointe maintenant directement sur le commit b. C’est connu comme étant l’état HEAD détachée. Ceci signifie simplement que HEAD fait référence à un commit spécifique, par opposition à une référence à une branche nommée. Voyons ce qui arrive quand un commit est créé :

$ edit; git add; git commit

     HEAD (se réfère au commit 'e')
      |
      v
      e
     /
a---b---c---d  branche 'master' (se réfère au commit 'd')
    ^
    |
  tag 'v2.0' (se réfère au commit 'b')

Il y a maintenant un nouveau commit e mais il est référencé seulement par HEAD. Un autre commit peut bien sûr être ajouté dans cet état :

$ edit; git add; git commit

	 HEAD (se réfère au commit 'f')
	  |
	  v
      e---f
     /
a---b---c---d  branche 'master' (se réfère au commit 'd')
    ^
    |
  tag 'v2.0' (se réfère au commit 'b')

En fait, toutes les opérations normales de Git peuvent être exécutées. Mais, regardons ce qui arrive quand master est extraite :

$ git checkout master

               HEAD (se réfère au branch 'master')
      e---f     |
     /          v
a---b---c---d  branche 'master' (se réfère au commit 'd')
    ^
    |
  tag 'v2.0' (se réfère au commit 'b')

Il est important de réaliser qu’à ce moment, rien ne fait référence au commit f. Finalement, le commit f (et par extension le commit e) sera supprimé par le processus de ramasse-miette régulier de Git, à moins de créer une référence avant que cela n’arrive. Si vous n’avez pas encore quitté le commit f, une des commandes suivantes permet de créer une référence sur lui :

$ git checkout -b foo  # ou "git switch -c foo"  (1)
$ git branch foo                                 (2)
$ git tag foo                                    (3)

crée une nouvelle branche foo qui fait référence au commit f, puis met à jour HEAD pour faire référence à la branche foo. En d’autres termes, l’état ne sera plus en HEAD détachée après cette commande.
crée aussi une nouvelle branche foo qui fait référence au commit f mais laisse HEAD détachée.
crée une nouvelle étiquette foo qui fait référence au commit f, en laissant HEAD détachée.

Si nous ne sommes plus sur f, alors nous devons d’abord retrouver son nom d’objet (typiquement en utilisant git reflog), puis nous pouvons créer une référence dessus. Par exemple, pour voir les deux derniers commits sur lesquels HEAD pointait, nous pouvons utiliser l’une des commandes suivantes :

$ git reflog -2 HEAD # ou
$ git log -g -2 HEAD

DÉSAMBIGUÏSATION D’ARGUMENT

Quand il n’y a qu’un argument fourni et qu’il n’est pas -- (par exemple git checkout abc) et quand l’argument est à la fois un <arbre-esque> valide (par exemple une branche abc existe) et un <spécificateur_de_chemin> valide (par exemple un fichier ou un répertoire du nom de « abc » existe), Git vous demandera généralement de lever l’ambiguïté. Du fait qu’extraire une branche est une opération très commune, cependant, git checkout abc considère « abc » comme un <arbre-esque> dans une telle situation. Utilisez git checkout -- <spécificateur_de_chemin> si vous voulez extraire ces chemins depuis l’index.

EXEMPLES

1. Chemins

La séquence suivante extrait la branche master, ramène le fichier Makefile à deux révisions en arrière, supprime hello.c par erreur et le récupère de l’index.

$ git checkout master             (1)
$ git checkout master~2 Makefile  (2)
$ rm -f hello.c
$ git checkout hello.c            (3)

bascule de branche
prend un fichier depuis un autre commit
restaure hello.c depuis l’index

Si vous souhaitez extraire tous les fichiers source C de l’index, vous pouvez lancer

$ git checkout -- '*.c'

Notez les guillemets autour de *.c. Le fichier hello.c sera aussi extrait, même s’il n’est plus dans l’arbre de travail, parce que le patron de fichier est utilisé pour trouver les entrées dans l’index (et non dans l’arbre de travail par le shell).

Si vous avez une branche qui s’appelle malheureusement hello.c, cette étape pourrait être confondue avec une instruction de basculer sur cette branche. Vous devriez alors plutôt écrire :

$ git checkout -- hello.c

2. Fusion

Après avoir travaillé dans la mauvaise branche, basculer sur la branche correcte serait réalisé par :

$ git checkout monsujet

Cependant, votre « fausse » branche et votre branche correcte monsujet peuvent être différentes par les fichiers que vous avez modifiés localement, auquel cas l’extraction ci-dessus échouerait comme ceci :

$ git checkout monsujet
error: Vos modifications locales aux fichiers suivants seraient écrasées par l'extraction :

Vous pouvez fournir l’option -m à la commande, ce qui essaierait une fusion à trois points :

$ git checkout -m monsujet
Fusion automatique de frotz

Après cette fusion à trois points, les modifications locales ne sont pas enregistrées dans votre index, donc git diff vous montrerait ce qui a changé depuis le sommet de la nouvelle branche.

3. Conflit de fusion

Quand un conflit de fusion arrive pendant un basculement de branche avec l’option -m, vous devriez voir quelque chose comme :

$ git checkout -m mytopic
Fusion automatique de frotz
CONFLIT (contenu): Conflit de fusion dans frotz
fatal: merge program failed

À ce stade, git diff affiche les modifications proprement fusionnées comme dans l’exemple précédent, ainsi que les modifications en conflit. Éditez et résolvez le conflit et marquez-le résolu avec git add comme d’habitude :

$ edit frotz
$ git add frotz

CONFIGURATION

Warning

Missing fr/includes/cmd-config-section-all.txt

See original version for this content.

Warning

Missing fr/config/checkout.txt

See original version for this content.

VOIR AUSSI

git-switch[1], git-restore[1]

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