La commande `git checkout` est partout, mais elle est source de confusion. Pas de panique, c’est normal.
Ce guide vous explique pourquoi elle est compliquée et comment utiliser ses remplaçants modernes : `git switch` et `git restore`.
Le double rôle de git checkout : la raison de sa complexité
Le principal problème de `git checkout` est simple : elle fait deux choses très différentes. Elle sert à la fois à changer de branche et à restaurer des fichiers. Cette double fonction la rend peu intuitive et parfois dangereuse.
Pour clarifier les choses, Git a introduit deux nouvelles commandes dédiées à partir de la version 2.23. Elles remplacent `git checkout` pour rendre les opérations plus claires.
git switch: sert uniquement à changer de branche ou de commit. Son rôle est clair et limité.git restore: sert uniquement à restaurer des fichiers depuis l’historique, l’index ou le répertoire de travail.
En gros, l’ancienne commande a été scindée en deux pour que chaque outil fasse une seule chose, mais la fasse bien. Adopter `git switch` et `git restore` est aujourd’hui la méthode recommandée.
Les 3 états d’un fichier dans Git : la clé pour tout comprendre
Pour vraiment maîtriser Git et comprendre pourquoi des commandes comme `checkout` ou `restore` fonctionnent, il faut connaître les trois « endroits » où un fichier peut exister dans votre projet. Chaque version a un rôle précis.
1. Le working tree (ou répertoire de travail)
C’est le plus simple à comprendre. Le « working tree » est simplement le dossier de votre projet sur votre ordinateur. Ce sont les fichiers que vous voyez, que vous ouvrez et que vous modifiez avec votre éditeur de code.
Quand vous modifiez un fichier, vous le modifiez dans le répertoire de travail. À ce stade, Git sait que le fichier a changé, mais ce changement n’est pas encore enregistré dans l’historique du projet.
2. L’index (ou staging area)
L’index, aussi appelé « staging area » ou « cache », est une zone de préparation pour le prochain commit. C’est une étape intermédiaire entre vos modifications locales et leur enregistrement définitif dans l’historique.
Quand vous êtes satisfait de vos modifications dans le répertoire de travail, vous utilisez la commande git add . Cette action ne sauvegarde rien de manière permanente. Elle copie simplement la version actuelle du fichier dans l’index, pour dire à Git : « Je veux que cette version du fichier soit incluse dans le prochain commit ».
3. Le commit (HEAD)
Un commit est un instantané (snapshot) de votre projet à un moment donné. Il est stocké dans la base de données de Git et ne peut plus être modifié. Chaque commit a un identifiant unique (un hash).
La commande git commit prend tout ce qui se trouve dans l’index (la staging area) et en fait un nouveau point de sauvegarde permanent. Le commit n’utilise pas les fichiers de votre répertoire de travail, mais bien ceux que vous avez ajoutés à l’index. Le pointeur `HEAD` indique simplement sur quel commit vous vous trouvez actuellement.
Le flux de travail standard dans Git :
- Vous modifiez un fichier dans votre répertoire de travail (working tree).
- Vous ajoutez cette modification à la zone de préparation avec
git add. Le fichier passe dans l’index. - Vous enregistrez l’instantané de l’index comme un point de sauvegarde permanent avec
git commit.
Cas d’usage 1 : Restaurer des fichiers (l’ancien git checkout — <fichier> vs le nouveau git restore)
Un des rôles de `git checkout` était de restaurer un fichier à une version précédente. C’était une opération courante mais qui pouvait être risquée. La nouvelle commande `git restore` rend ce processus plus sûr et plus lisible.
L’ancienne méthode : `git checkout — `
La commande git checkout -- nom_du_fichier permettait de remplacer le fichier dans votre répertoire de travail par la version qui se trouve dans l’index. Si vous aviez fait des modifications non désirées, c’était un moyen de les annuler.
Le problème, c’est que cette commande peut écraser votre travail sans confirmation. Si vous aviez des modifications importantes dans votre fichier mais que vous ne les aviez pas encore ajoutées à l’index, elles étaient perdues pour de bon.
La nouvelle méthode : `git restore`
La commande `git restore` est beaucoup plus explicite. Elle vous donne un contrôle total sur ce que vous restaurez et où vous le restaurez. Elle distingue clairement l’index du répertoire de travail.
Ses options principales sont :
-S(ou--staged) : pour agir sur la version du fichier dans l’index (staging area).-W(ou--worktree) : pour agir sur la version du fichier dans le répertoire de travail.--source: pour spécifier de quel commit vous voulez récupérer le fichier.
Exemple concret avec git restore :
Imaginons que vous vouliez restaurer le fichier `hello.txt` à la version du commit `11cb5b6`, mais uniquement dans votre répertoire de travail (sans toucher à l’index) :
git restore --source 11cb5b6 --worktree -- hello.txt
Cette commande est claire : la source est un commit précis et la destination est le répertoire de travail. Il n’y a aucune ambiguïté.
Cas d’usage 2 : Changer de branche ou de commit (l’ancien git checkout <branche> vs le nouveau git switch)
Le second grand rôle de `git checkout` est de naviguer dans l’historique du projet, c’est-à-dire de changer de branche ou de revenir à un ancien commit. Là aussi, `git switch` apporte plus de clarté.
L’ancienne méthode : `git checkout `
Utiliser git checkout master ou git checkout une-autre-branche met à jour tout votre répertoire de travail pour qu’il corresponde à l’état de cette branche. C’est une opération qui modifie de nombreux fichiers d’un seul coup.
On pouvait aussi l’utiliser pour voyager dans le temps en se déplaçant sur un commit précis :
git checkout HEAD~1: pour revenir au commit précédent.git checkout <identifiant_commit>: pour se placer sur un commit spécifique de l’historique.
Une option particulièrement dangereuse était git checkout -m. En cas de conflit de fusion, cette option pouvait écraser vos modifications locales ou recréer un état de conflit, entraînant une perte de travail.
La nouvelle méthode : `git switch`
La commande git switch est conçue uniquement pour la navigation entre les branches. Son nom est explicite et son usage est plus sûr.
Pour changer de branche, il suffit de faire :
git switch nom-de-la-branche
L’avantage est que git switch possède des garde-fous pour éviter la perte de modifications non sauvegardées. Si vous avez du travail en cours dans votre répertoire de travail qui entrerait en conflit avec la branche de destination, la commande refusera de s’exécuter et vous demandera de sauvegarder votre travail d’abord (`commit` ou `stash`).
Astuce : nommer un commit avec un tag
Les identifiants de commit (comme `30676ede3a…`) sont difficiles à mémoriser. Pour donner un nom lisible à un commit important, vous pouvez utiliser la commande git tag.
Par exemple : git tag v1.0 30676ede3a
Ensuite, vous pourrez revenir à ce commit simplement avec git checkout v1.0 (ou `git switch v1.0`).
Pour les experts : `git checkout-index`, la copie directe depuis l’index
Il existe une autre commande, plus rare, qui est liée à ce processus : git checkout-index. Elle est destinée à des usages plus avancés, notamment pour des scripts ou des exports de fichiers.
Son rôle est très spécifique : elle copie des fichiers depuis l’index vers le répertoire de travail. Elle ne lit pas les commits, seulement ce qui a été préparé avec `git add`.
Voici quelques options utiles :
-f(ou--force) : force l’écrasement des fichiers existants dans le répertoire de travail.-a(ou--all) : copie tous les fichiers de l’index, pas seulement ceux spécifiés.-n(ou--no-create) : ne crée pas de nouveaux fichiers, mais met à jour ceux qui existent déjà.--prefix=<chaîne>: ajoute un préfixe de chemin à tous les fichiers copiés. C’est très utile pour exporter le projet dans un sous-dossier.
Exemple : exporter tout le projet dans un nouveau dossier
Si vous voulez créer une copie propre de tous les fichiers présents dans l’index dans un dossier nommé `export/`, vous pouvez utiliser cette commande :
git checkout-index --prefix=export/ -a
Cela va recréer toute l’arborescence de votre projet à l’intérieur du dossier `export/`, sans y inclure le dossier `.git` ou les fichiers non suivis.
En résumé, `git checkout` est une commande puissante mais dépassée. Pour un travail plus clair, plus sûr et plus moderne, il est temps de passer à ses successeurs.
Utilisez git switch pour changer de branche et git restore pour annuler des modifications sur des fichiers. Vos commandes seront plus lisibles et vous réduirez les risques d’erreur.
