git switch ou git checkout : lequel utiliser ?

En bref : pour changer de branche, utilise git switch ; pour annuler les modifications d'un fichier, utilise git restore. git checkout sait faire les deux et fonctionne toujours, mais depuis Git 2.23 (août 2019), ces deux commandes se partagent ses deux métiers et disent clairement ce que tu t'apprêtes à faire.

Tu croiseras encore git checkout un peu partout : dans les tutos écrits avant 2019, dans les réponses de Stack Overflow, dans les réflexes de tes collègues. Rien de grave, les deux familles de commandes donnent le même résultat. Voici comment passer de l'une à l'autre, et laquelle apprendre en premier.

Pourquoi Git a ajouté git switch et git restore

La documentation officielle de git checkout l'annonce dès sa première ligne : la commande a deux modes principaux. Elle change de branche (git checkout main) et elle restaure une version d'un fichier (git checkout -- contact.html). Quand tu tapes git checkout quelque-chose, Git essaie de deviner si tu parles d'une branche, d'un commit ou d'un fichier.

Le souci, c'est que ces deux métiers n'ont pas du tout le même niveau de risque :

• Changer de branche est sans danger : si l'opération risquait d'écraser des modifications non commitées, Git refuse et te prévient.
• Restaurer un fichier est destructeur : git checkout -- contact.html remplace ton fichier par sa dernière version enregistrée, sans demander de confirmation. Les modifications effacées n'avaient jamais été enregistrées par Git : il ne peut pas te les rendre.

Une même commande pour une action anodine et pour une action irréversible, c'est un piège, surtout quand on débute. Git 2.23, sorti le 16 août 2019, a donc ajouté deux commandes qui font chacune un seul de ces métiers : git switch pour les branches, git restore pour les fichiers.

Et la mention « expérimental » ?

À leur sortie, git switch et git restore portaient dans leur documentation l'avertissement « THIS COMMAND IS EXPERIMENTAL. THE BEHAVIOR MAY CHANGE. ». Ce n'est plus le cas : les notes de version de Git 2.51 (août 2025) les déclarent officiellement sorties de la phase expérimentale. Si tu lis encore cet avertissement, la page que tu consultes, ou ta version de Git, date d'avant.

Le tableau d'équivalences

La vraie différence est ailleurs : git switch n'accepte que des branches (ou un commit, si tu ajoutes --detach), et git restore que des fichiers. Une faute de frappe ne peut donc plus te faire restaurer un fichier quand tu voulais changer de branche :

$ git switch contact.htmlfatal: invalid reference: contact.html

Créer une branche et changer de branche

$ git switch -c formulaire-contactSwitched to a new branch 'formulaire-contact'$ git switch mainSwitched to branch 'main'$ git switch -Switched to branch 'formulaire-contact'

Ce qu'il faut retenir :

• -c comme *create* : Git crée la branche à partir de ta position actuelle, puis s'y place. Si elle existe déjà, il refuse avec fatal: a branch named 'formulaire-contact' already exists.
• git switch - te ramène à la branche où tu étais juste avant. Pratique pour les allers-retours.
• Une branche qui n'existe que sur le dépôt distant, par exemple celle d'un·e collègue après un git fetch : git switch formulaire-contact crée la branche locale et la relie à origin/formulaire-contact. Git l'annonce par branch 'formulaire-contact' set up to track 'origin/formulaire-contact'. (git checkout fait la même chose).

Comme checkout, git switch refuse de changer de branche si tes modifications non commitées risquent d'être écrasées :

$ git switch formulaire-contacterror: Your local changes to the following files would be overwritten by checkout:        index.htmlPlease commit your changes or stash them before you switch branches.Aborting

Le message parle de « checkout » même quand tu tapes git switch : dans le code source de Git, les deux commandes partagent le même fichier et le même mécanisme. Commite tes modifications ou mets-les de côté avec git stash, puis recommence.

Toutes les options sont détaillées dans git switch expliqué, et la gestion des branches elles-mêmes (lister, renommer, supprimer) dans git branch expliqué.

Restaurer un fichier

git status te le suggère lui-même : pour annuler les modifications d'un fichier, ses conseils proposent git restore.

$ git statusOn branch mainChanges not staged for commit:  (use "git add <file>..." to update what will be committed)  (use "git restore <file>..." to discard changes in working directory)        modified:   contact.html no changes added to commit (use "git add" and/or "git commit -a") $ git restore contact.html$ git statusOn branch mainnothing to commit, working tree clean

Deux autres usages reviennent souvent :

• Retirer un fichier de l'index sans perdre tes modifications : git restore --staged contact.html. C'est l'inverse de git add, et c'est ce que git status te propose (use "git restore --staged <file>..." to unstage). Les tutos plus anciens utilisent git reset HEAD contact.html pour la même chose.
• Reprendre la version d'une autre branche : git restore --source=main contact.html. Attention à une nuance : git checkout main -- contact.html met aussi le fichier dans l'index, alors que git restore ne touche par défaut qu'à ton répertoire de travail. Pour obtenir exactement le même résultat, ajoute --staged --worktree.

Le reste des options, avec des exemples, est dans git restore expliqué.

La HEAD détachée : là où switch te protège

D'habitude, HEAD (ta position dans l'historique) pointe sur une branche. Si tu te places directement sur un commit, HEAD est dite « détachée » : tu peux regarder le code tel qu'il était, mais les commits que tu ferais à cet endroit n'appartiennent à aucune branche, et tu risques de les perdre de vue en repartant.

Avec git checkout, il suffit de donner un commit (ou un tag) pour y aller, et Git t'explique après coup où tu es :

$ git checkout fc8062dNote: switching to 'fc8062d'. You are in 'detached HEAD' state. You can look around, make experimentalchanges and commit them, and you can discard any commits you make in thisstate without impacting any branches by switching back to a branch. If you want to create a new branch to retain commits you create, you maydo so (now or later) by using -c with the switch command. Example:   git switch -c <new-branch-name> Or undo this operation with:   git switch - Turn off this advice by setting config variable advice.detachedHead to false HEAD is now at fc8062d Premier commit

Remarque que même ce message de checkout te renvoie vers git switch -c et git switch -.

git switch, lui, refuse tant que tu n'as pas confirmé avec --detach :

$ git switch fc8062dfatal: a branch is expected, got commit 'fc8062d'hint: If you want to detach HEAD at the commit, try again with the --detach option.$ git switch --detach fc8062dHEAD is now at fc8062d Premier commit

C'est pareil avec un tag : git switch v1.0 répond fatal: a branch is expected, got tag 'v1.0'. Pour revenir sur ta branche, tape git switch - ou git switch main. Et si tu as fait des commits en HEAD détachée que tu veux garder, crée d'abord une branche pour eux avec git switch -c nouvelle-branche. Le détail, y compris comment retrouver des commits déjà perdus de vue, est dans notre fiche sur l'erreur detached HEAD.

Lequel apprendre ?

Si tu débutes, apprends git switch et git restore. Chaque commande fait une seule chose, son nom dit ce qu'elle fait, et elle refuse les cas ambigus : un nom de fichier passé à switch, un commit sans --detach. Les messages de Git eux-mêmes, dans git status comme dans l'avertissement de HEAD détachée, te proposent ces commandes.

Apprends quand même à lire git checkout. Tu le trouveras dans tous les tutos écrits avant 2019, dans des scripts et dans les habitudes de personnes qui utilisent Git depuis longtemps. La documentation officielle ne le marque ni comme déprécié ni comme obsolète. Le tableau plus haut suffit pour traduire d'une forme à l'autre, et la page git checkout expliqué détaille ses options.

Seule condition pour switch et restore : avoir Git 2.23 ou plus récent. Tape git --version pour le vérifier.

Questions fréquentes

git checkout est-il déprécié ?

Non. La documentation officielle de Git présente toujours git checkout avec ses deux modes, sans aucune mention de dépréciation. git switch et git restore sont des alternatives plus spécialisées, pas des remplaçantes obligatoires.

git switch est-il encore expérimental ?

Non. Git 2.51, sorti en août 2025, a retiré la mention expérimentale de git switch et de git restore : c'est écrit dans ses notes de version. Tu peux encore la voir dans des documentations ou des tutos plus anciens.

Quelle est la différence entre git switch -c et git checkout -b ?

Aucune dans le résultat : les deux créent une branche à partir de ta position actuelle et s'y placent. Le -c de switch vient de create, le -b de checkout vient de branch.

Pourquoi git switch refuse-t-il d'aller sur un commit ?

Pour t'éviter de passer en HEAD détachée par erreur. Si c'est bien ce que tu veux, par exemple pour examiner une ancienne version du projet, ajoute l'option prévue : git switch --detach <commit>.

Comment annuler les modifications d'un fichier avec git restore ?

Tape git restore <fichier> : le fichier revient à son état du dernier git add, ou du dernier commit si tu ne l'as pas ajouté depuis. Les modifications annulées sont perdues définitivement, alors vérifie avec git diff avant.

Quelle version de Git faut-il pour utiliser git switch ?

Git 2.23 ou plus récent, sorti en août 2019. Vérifie la tienne avec git --version. Si elle est plus ancienne, mets Git à jour ou continue avec git checkout, qui fait la même chose.