git checkout

Ce que fait git checkout

git checkout est l'une des commandes les plus polyvalentes de Git. Elle remplit deux rôles distincts :

1. Changer de branche — déplacer HEAD pour pointer vers une autre branche et mettre à jour les fichiers de votre répertoire de travail pour correspondre au dernier commit de cette branche.
2. Restaurer des fichiers — écraser des fichiers dans votre répertoire de travail (ou la zone de staging) avec une version provenant d'un commit, d'une branche ou de l'index.

HEAD est le pointeur de Git vers « là où vous êtes maintenant » — normalement le sommet de la branche que vous avez extraite. Lorsque vous exécutez git checkout, Git déplace HEAD et réécrit vos fichiers suivis afin que l'arbre de travail reflète la cible.

Parce que la commande est surchargée, le Git moderne (2.23+) a divisé ses deux rôles en deux commandes plus claires : git switch pour se déplacer entre les branches et git restore pour annuler les modifications apportées aux fichiers. git checkout fonctionne toujours exactement comme avant et est présentée tout au long de cette page, avec les équivalents modernes indiqués lorsque c'est utile.

Cette page couvre l'extraction des branches existantes et nouvelles, le travail avec les branches distantes, la restauration de fichiers et l'état « HEAD détaché ».

Extraire une branche existante

Si un dépôt contient déjà plusieurs branches, git checkout <branch> permet de basculer vers l'une d'elles. Exécutez d'abord git branch pour lister les branches disponibles ; la branche courante est marquée d'un astérisque :

Lister les branches et basculer vers l'une d'elles

$ git branch
* master
  test_branch
  feature_branch

$ git checkout feature_branch
Switched to branch 'feature_branch'

Après le changement, votre répertoire de travail correspond au dernier commit sur feature_branch, et tout nouveau commit que vous créez y est enregistré. L'équivalent moderne est git switch feature_branch.

Git refuse de changer de branche si vous avez des modifications non commitées qui seraient écrasées par la branche cible. Dans ce cas, commitez-les, remisez-les ou rejetez-les d'abord.

Créer et extraire une nouvelle branche

Pour créer une branche et y basculer en une seule étape, utilisez l'option -b :

git checkout -b

git checkout -b new_branch

L'option -b indique à Git d'exécuter git branch new_branch (créer la branche à partir du HEAD actuel) puis immédiatement git checkout new_branch. C'est équivalent à :

git branch new_branch
git checkout new_branch

Par défaut, la nouvelle branche commence à partir de votre HEAD actuel. Pour la baser sur une branche ou un commit différent, indiquez un point de départ :

git checkout -b à partir d'un point de départ spécifique

git checkout -b new_branch existing_branch

Ici, new_branch est créée au sommet de existing_branch plutôt qu'au HEAD actuel. L'équivalent moderne est git switch -c new_branch existing_branch.

Changer de branche et HEAD

Exécuter git checkout <branch> pointe HEAD vers le sommet de cette branche :

git checkout main

Si vous changez de branche par erreur ou perdez trace de la position de HEAD, la commande git reflog liste chaque position que HEAD a occupée, afin que vous puissiez revenir à un état antérieur.

Extraire une branche distante

Lorsque vous travaillez en équipe, le dépôt distant contient des branches que d'autres personnes ont poussées. Pour les voir et les extraire, téléchargez d'abord les dernières données distantes avec git fetch :

git fetch --all

Le Git moderne peut ensuite extraire une branche distante par son nom court. Git crée automatiquement une branche locale qui suit la branche distante correspondante :

git checkout feature_branch

Cela fonctionne uniquement lorsqu'un seul dépôt distant possède une branche de ce nom. Si le nom est ambigu, ou si vous voulez être explicite, créez une branche locale de suivi à partir de la référence distante :

Créer une branche locale à partir d'une branche distante

git checkout -b feature_branch origin/feature_branch

L'option -b est requise ici — la nouvelle branche locale feature_branch est créée au niveau de origin/feature_branch et configurée pour la suivre. Pour forcer une branche locale existante à correspondre exactement au sommet distant, utilisez git reset :

git reset --hard origin/feature_branch

git reset --hard supprime les commits locaux et les modifications non commitées sur cette branche, donc utilisez-la uniquement lorsque vous avez l'intention de supprimer le travail local.

Restaurer des fichiers avec git checkout

En plus de changer de branche, git checkout peut remplacer des fichiers dans votre arbre de travail avec une version provenant de l'index ou d'un autre commit.

Annuler les modifications non commitées d'un fichier unique et restaurer la version du dernier commit :

Annuler les modifications d'un fichier

git checkout -- file.txt

Le -- sépare les options de la commande du chemin du fichier, ce qui évite toute ambiguïté lorsqu'un fichier et une branche portent le même nom. L'équivalent moderne est git restore file.txt.

Restaurer un fichier tel qu'il existait dans un commit ou une branche spécifique, sans changer de branche :

Restaurer un fichier depuis un autre commit

git checkout <commit> -- file.txt

Cela met à jour file.txt dans votre répertoire de travail et la zone de staging avec son contenu dans <commit>, tandis que HEAD reste sur votre branche actuelle. Consultez git restore pour la syntaxe moderne plus claire.

État HEAD détaché

L'extraction d'un commit spécifique (plutôt que d'une branche) vous place dans un état de HEAD détaché :

git checkout a1b2c3d

Normalement, HEAD pointe vers une branche, qui à son tour pointe vers un commit. Lorsque vous extrayez directement un commit, HEAD pointe directement sur ce commit sans branche attachée — c'est ce que signifie « détaché ». C'est utile pour examiner ou tester un ancien état du projet.

Le risque est que tout commit effectué dans cet état n'est sur aucune branche. Dès que vous extrayez une autre branche, ces commits n'ont plus de référence pointant vers eux et deviennent difficiles à retrouver (Git finira par les supprimer via le ramasse-miettes). Si vous décidez de conserver le travail effectué dans un HEAD détaché, donnez-lui une branche avant de partir :

git switch -c new_branch

Ainsi : examiner un ancien commit dans un HEAD détaché est parfaitement sûr, mais effectuez tout nouveau développement sur une vraie branche afin que vos commits restent accessibles. La commande git reflog peut toujours vous aider à récupérer des commits si vous oubliez.

Pratique