git checkout
Changer de branche ou restaurer des fichiers de l’arbre de travail
git checkout est une commande polyvalente qui change de branche, crée de nouvelles branches, restaure des fichiers depuis des commits précis et peut mettre votre dépôt en état « HEAD détaché ». Même si les versions récentes de Git ont réparti une partie de ses fonctions entre « git switch » et « git restore », checkout reste très utilisé et bien connu.
Synopsis
git checkout <branch>
git checkout -b <new-branch> [<start-point>]
git checkout -B <branch> [<start-point>]
git checkout --detach [<branch>]
git checkout [--] <pathspec>...
git checkout <commit> -- <pathspec>...Options
Choisir la bonne option
Créer des branches
Différentes façons de créer une nouvelle branche et d’y basculer
| Commande | Si la branche existe | Historique | Idéal pour |
|---|---|---|---|
-b <name> | Échoue avec une erreur | Normale (reliée) | Travail standard sur une nouvelle fonctionnalité |
-B <name> | Replacée sur le commit courant | Normale (reliée) | Recommencer une branche à zéro |
--orphan <name> | Échoue avec une erreur | Aucun (déconnectée) | gh-pages, docs, page blanche |
Changer de branche avec des modifications non committées
Ce qui arrive à vos modifications locales quand vous changez de branche
| Commande | Modifications non committées | Niveau de risque | Quand l’utiliser |
|---|---|---|---|
git checkout <branch> | Bloqué en cas de conflit | Sans risque | Comportement par défaut - évite les accidents |
git checkout -f <branch> | Jetées définitivement | Dangereux | Abandonner volontairement toutes les modifications locales |
git checkout -m <branch> | Fusionnées par une fusion à trois voies | Moyen | Emporter les modifications sur une autre branche |
git stash + checkout | Mises de côté pour plus tard | Sans risque | Changement de contexte temporaire |
Restaurer des fichiers
Jeter ou restaurer le contenu de fichiers depuis différentes sources
| Commande | Source | Touche l’index | Récupérable |
|---|---|---|---|
-- <file> | Index (version indexée) | No | Non - modifications perdues pour toujours |
<commit> -- <file> | Un commit précis | Oui (indexé) | Non - mais indexé pour relecture |
-p -- <file> | Index (interactif) | No | Partiel - choisissez les blocs |
Suivi des branches distantes
Contrôler la relation entre branches locales et distantes
| Commande | Crée le suivi | Cas d’usage | git push/pull |
|---|---|---|---|
--track origin/feat | Oui (automatique) | Travailler sur la branche d’un collègue | Fonctionne sans arguments |
--no-track -b exp origin/main | Non (indépendante) | Expérimenter sans risque | Exige de nommer le dépôt distant |
<remote-branch> | Oui (si c’est sans ambiguïté) | Extraire rapidement une branche distante | Fonctionne sans arguments |
Résoudre des conflits de fusion
Choisir un côté pendant un conflit de fusion
| Commande | Garde | Jette | Quand l’utiliser |
|---|---|---|---|
--ours <file> | La version de votre branche | Modifications entrantes | Vos modifications sont les bonnes |
--theirs <file> | Version entrante | Vos modifications | Accepter leur implémentation |
(manual edit) | Résultat combiné | Rien | Besoin de parties des deux côtés |
checkout face aux commandes modernes
Git 2.23+ a séparé checkout en commandes ciblées
| Commande | Change de branche | Restaure des fichiers | Recommandé pour |
|---|---|---|---|
git checkout | Oui | Oui | Habitude, anciennes versions de Git |
git switch | Oui | No | Intention claire : opérations sur les branches seulement |
git restore | No | Oui | Intention claire : opérations sur les fichiers seulement |
Exemples de workflows
git stashMettre de côté le travail non committé en cours
git checkout other-branchPasser sur l’autre branche
(review or make quick fix)Faire le travail nécessaire sur cette branche
git checkout -Revenir à la branche précédente (raccourci)
git stash popRestaurer le travail mis de côté
git checkout mainPasser sur la branche main
git pull origin mainRécupérer les dernières modifications du dépôt distant
git checkout -b feature-nameCréer la nouvelle branche de fonctionnalité et y basculer
(make changes and commits)Travailler sur la fonctionnalité
git push -u origin feature-namePousser la branche et configurer le suivi
git statusVoir quels fichiers ont été modifiés
git diff file.jsRelire les modifications que vous allez jeter
git checkout -- file.jsJeter les modifications d’un fichier précis
git checkout -- .Ou jeter TOUTES les modifications non indexées des fichiers suivis
git log --onelineTrouver le hash du commit voulu
git checkout <commit-hash>Extraire ce commit précis (HEAD détaché)
(inspect, test, or debug)Examiner l’ancien code
git checkout mainRevenir sur la branche main une fois fini
git log --oneline -- file.jsTrouver les commits qui ont modifié ce fichier
git show <commit>:file.jsPrévisualiser l’ancienne version
git checkout <commit> -- file.jsRestaurer le fichier depuis ce commit (il est indexé)
git commit -m 'Restore file.js'Committer la version restaurée
git fetch originRécupérer les dernières infos sur les branches distantes
git branch -rVoir les branches distantes disponibles
git checkout --track origin/featureCréer une branche locale qui suit la distante
git pullMaintenant pull fonctionne sans préciser le dépôt distant
Dépannage
error: Your local changes to the following files would be overwritten by checkout
Cause : Vous avez des modifications non committées qui entrent en conflit avec la branche cible
Committez vos modifications, mettez-les dans le stash, ou utilisez -f pour forcer (jette les modifications)
git stash && git checkout branch && git stash poperror: pathspec 'branch-name' did not match any file(s) known to git
Cause : La branche n’existe pas, ou vous avez peut-être fait une faute de frappe dans le nom
Consultez les branches disponibles avec git branch -a, ou créez la branche avec -b
git branch -a | grep branch-nameYou are in 'detached HEAD' state
Cause : Vous avez extrait un hash de commit ou un tag au lieu d’un nom de branche
Si vous voulez continuer à travailler, créez une branche. Sinon, extrayez une branche existante
git checkout -b new-branch-nameLes commits faits en HEAD détaché sont perdus
Cause : Vous avez fait des commits en HEAD détaché puis êtes passé sur une autre branche
Retrouvez les commits avec le reflog et créez une branche pour les garder
git reflog && git branch recovered-work <commit-hash>Checkout impossible : un fichier non suivi serait écrasé
Cause : Vous avez des fichiers non suivis qui existent dans la branche cible
Supprimez, déplacez ou mettez d’abord ces fichiers non suivis dans le stash
git stash --include-untracked && git checkout branchModifications jetées par erreur avec checkout --
Cause : git checkout -- <file> supprime définitivement les modifications non committées
Malheureusement, Git ne peut pas les récupérer. Regardez l’historique local de votre éditeur
(check IDE local history if available)fatal: 'name' could be both a local file and a tracking branch
Cause : Un fichier ou un dossier porte le même nom que la branche distante que vous voulez extraire
Ajoutez un -- à la fin pour dire à Git que ce nom est une branche, ou utilisez git switch
git checkout branch-name --La branche ne se met pas à jour après le checkout
Cause : Vous avez peut-être extrait directement une branche de suivi distante
Créez une branche de suivi locale au lieu d’extraire directement origin/branch
git checkout --track origin/branch-nameAstuces et pièges
Bonnes pratiques
- ✓Utilisez 'git stash' avant de changer de branche si vous avez du travail non committé à garder
- ✓Préférez 'git checkout -b' à 'git branch' + 'git checkout' séparés pour créer une branche et y basculer
- ✓Utilisez '--' pour séparer clairement les chemins de fichiers des noms de branche : 'git checkout -- file.txt'
- ✓Pensez aux commandes modernes 'git switch' pour les branches et 'git restore' pour les fichiers - l’intention est plus claire
- ✓Utilisez 'git checkout -' pour revenir rapidement à la branche précédente (comme 'cd -')
- ✓Avant d’utiliser '-f' pour forcer le checkout, assurez-vous de vraiment vouloir jeter vos modifications
- ✓En HEAD détaché, créez tout de suite une branche si vous comptez faire des commits
- ✓Utilisez '--track' en extrayant des branches distantes pour configurer push/pull automatiquement
- ✓Utilisez 'git checkout <commit> -- <file>' pour restaurer certains fichiers sans changer de branche
- ✓Évitez d’extraire directement des commits sauf pour enquêter - utilisez des noms de branche pour le travail courant
- ✓Utilisez '-p' (mode patch) pour ne jeter que certaines modifications d’un fichier
- ✓Vérifiez toujours que vous êtes sur la bonne branche avec 'git branch' ou 'git status' avant de commencer à travailler
Erreurs fréquentes
- ✗Tenter un checkout avec des modifications non committées. Git refuse de changer de branche s’il devait écraser vos modifications - committez, faites un stash, ou utilisez -f pour forcer (jette les modifications).
- ✗Confondre checkout pour les branches et pour les fichiers. Restaurer des fichiers par erreur en voulant changer de branche - mettez -- avant les chemins : git checkout -- file.txt
- ✗Faire des commits en HEAD détaché. Ces commits deviennent orphelins dès que vous extrayez une autre branche - créez d’abord une branche : git checkout -b my-branch
- ✗Utiliser -B sans comprendre qu’il écrase. Cela peut faire perdre la position de la branche existante - utilisez -b pour les nouvelles branches, et -B seulement pour une remise à zéro voulue.
FAQ
'git switch' est une commande plus récente (Git 2.23+) qui ne fait que changer de branche, ce qui la rend plus claire et plus sûre. 'git checkout' peut à la fois changer de branche ET restaurer des fichiers, ce qui peut prêter à confusion. Utilisez 'git switch' pour les branches et 'git restore' pour les fichiers si vous préférez l’approche moderne.
Malheureusement, Git seul ne peut pas l’annuler - les modifications sont jetées définitivement. Certains IDE ont un historique local qui peut aider. C’est pour cela qu’il faut être prudent avec cette commande.
HEAD détaché signifie que vous avez extrait un commit précis plutôt qu’une branche. Vous pouvez explorer et faire des commits, mais ils n’appartiendront à aucune branche. Créez une branche avec 'git checkout -b name' pour garder votre travail.
'-b' crée une nouvelle branche et échoue si elle existe déjà. '-B' crée une nouvelle branche ou replace une branche existante sur la position courante. Utilisez '-B' quand vous voulez volontairement remettre une branche à zéro.
Utilisez 'git checkout other-branch -- path/to/file'. Cela copie le fichier de cette branche dans votre répertoire de travail et votre zone de préparation. Vous pouvez ensuite le committer sur votre branche courante.
Git vous protège contre la perte de travail. Si changer de branche devait écraser vos modifications, il refuse. Committez vos modifications, mettez-les de côté avec 'git stash', ou utilisez 'git checkout -f' pour forcer (ce qui jette les modifications).
Il revient à la branche extraite précédemment, comme 'cd -' dans le shell. C’est un moyen rapide d’alterner entre deux branches sur lesquelles vous travaillez.
Faites d’abord 'git fetch origin', puis soit 'git checkout branch-name' (Git crée automatiquement une branche de suivi si origin/branch-name existe), soit explicitement 'git checkout --track origin/branch-name'.
Oui, utilisez 'git checkout -p <commit> -- <file>' pour le mode interactif, ou simplement 'git checkout <commit> -- <specific-files>' pour ne restaurer que certains fichiers de ce commit.
Parce qu’il fait deux choses très différentes : changer de branche ET restaurer des fichiers. Git 2.23 a introduit 'git switch' et 'git restore' pour séparer ces rôles. 'git checkout' fonctionne toujours et reste très utilisé.