Git switch vs checkout : comprendre la différence

Pendant longtemps, git checkout gérait presque tout ce qui concernait la navigation dans un dépôt, le passage d’une branche à l’autre, la restauration de fichiers et l’inspection d’anciens commits. Cette flexibilité apportait de l’ambiguïté. La même syntaxe pouvait signifier des choses différentes selon le contexte.

Une petite faute de frappe pouvait vous faire changer de branche alors que vous vouliez simplement restaurer un fichier. Un rapide retour en arrière avec git checkout <commit-hash> pouvait vous laisser dans un état de HEAD détachée sans que vous vous en rendiez compte. La commande fonctionnait, mais elle exigeait une vigilance constante quant à ses multiples comportements.

C’est pour cela que Git 2.23 a introduit git switch, une commande plus spécialisée dédiée aux opérations sur les branches.

Dans ce guide, je vais vous montrer en quoi git switch diffère de git checkout. Nous verrons également comment chaque commande s’intègre dans les workflows modernes et quel est leur périmètre respectif.

Si Git est encore relativement nouveau pour vous, je vous recommande d’apprendre les bases avec notre cours Introduction to Git.

Qu’est-ce que git switch ?

git switch est une commande dédiée, introduite avec Git 2.23, pour gérer la navigation entre les branches et leur création. Elle rend les déplacements entre branches plus clairs, plus sûrs et moins sujets aux erreurs.

Avant son arrivée, les développeurs utilisaient git checkout pour changer de branche. Le problème, c’est que git checkout gérait plusieurs tâches sans rapport :

• Changer de branche
• Restaurer des fichiers
• Inspecter des commits

La commande était donc surchargée et plus facile à mal utiliser.

Git a réglé cela en séparant les responsabilités. git switch gère désormais le changement et la création de branches, tandis que git restore s’occupe de la restauration de fichiers. Cette séparation réduit l’ambiguïté et diminue le risque de modifications accidentelles.

Concrètement, git switch branch-name déplace votre pointeur HEAD courant vers la branche indiquée. Vous pouvez aussi utiliser git switch -c new-branch pour créer et basculer vers une nouvelle branche.

Mécaniques de base : git switch vs checkout

Maintenant que vous savez pourquoi git switch a été introduit, voyons en quoi il diffère de git checkout sous le capot.

Gestion des branches pensée pour cet usage

Avant Git 2.23, git checkout gérait à la fois la navigation entre branches et la restauration de fichiers. Cette conception fonctionnait, mais mélangeait deux concepts fondamentalement différents. Elle déplaçait HEAD, restaurait des fichiers et permettait de vérifier des commits. Selon l’usage, elle manipulait le pointeur HEAD, l’index et l’arborescence de travail.

git switch se concentre exclusivement sur le déplacement du pointeur HEAD entre les branches. Lorsque vous exécutez git switch branch-name, Git met à jour HEAD pour pointer vers cette branche et aligne votre répertoire de travail en conséquence. Cette commande existe donc spécifiquement pour la navigation et la création de branches. Avec git switch et git restore, les responsabilités sont nettement séparées :

• git switch déplace HEAD entre les branches.

• git restore modifie les fichiers dans l’arborescence de travail ou l’index.

Par exemple, restaurer un fichier nécessitait auparavant : git checkout HEAD -- file.txt. Aujourd’hui, l’approche recommandée est : git restore file.txt.

Ici, vous restaurez un fichier, vous ne naviguez pas entre les branches. Dans les scripts et la documentation d’équipe, cette distinction améliore la lisibilité et réduit les erreurs.

Évolution des commandes Git

Git 2.23 sépare les responsabilités en introduisant git switch pour les opérations sur les branches et git restore pour la restauration de fichiers.

Avant cette version, git checkout faisait office d’outil polyvalent. Il pouvait changer de branche, restaurer des fichiers ou se déplacer vers des commits arbitraires. Mais cela engendrait de la confusion, surtout pour les nouveaux utilisateurs. En scindant la commande, Git a réduit l’ambiguïté et clarifié les workflows courants.

Comportement en cas de HEAD détachée

Dans Git, HEAD pointe normalement vers une branche. Cette branche pointe à son tour vers le dernier commit. Lorsque vous créez un nouveau commit, Git fait avancer la branche. C’est le fonctionnement standard.

Une HEAD détachée survient lorsque HEAD pointe directement vers un commit au lieu d’une branche. Dans cet état, vous n’êtes plus sur une branche. Si vous créez un nouveau commit, Git le crée, mais aucune branche ne le référence. À moins de créer explicitement une branche, ces commits restent non référencés et peuvent être difficiles à retrouver ensuite.

Lorsque vous exécutez git checkout <commit-hash>, Git entre automatiquement en mode HEAD détachée. Git passe à ce commit et détache HEAD sans confirmation supplémentaire. Ce comportement est valide, mais on se retrouve facilement en mode détaché par inadvertance.

À l’inverse, git switch exige une mention explicite. Pour détacher HEAD, vous devez utiliser git switch --detach <commit-hash>. Sans l’option --detach, git switch n’opère que sur des branches. Cette conception réduit les états détachés accidentels et rend les workflows de branche plus sûrs et plus prévisibles.

Différences fonctionnelles clés entre git switch et checkout

Maintenant que nous avons couvert les différences de haut niveau, regardons la syntaxe, le périmètre et les aspects de sécurité.

Syntaxe des commandes et création

Pour créer et basculer vers une nouvelle branche avec git switch, exécutez git switch -c <branch-name>. Avec git checkout, la commande équivalente est git checkout -b <branch-name>.

Les deux créent une nouvelle branche et y basculent, mais la différence tient à la clarté de l’intention. Dans git switch, l’option -c indique explicitement que vous créez une branche, alors que dans git checkout, -b signifie historiquement « branch », mais l’intention est moins explicite.

git switch introduit aussi l’option -C : git switch -C <branch-name>. Son effet est plus fort que -c : elle crée la branche de force, ou la réinitialise si elle existe déjà. Ce comportement est explicite et centré sur les branches. Dans git checkout, un comportement similaire existe, mais la sémantique est moins nette car la commande remplit plusieurs rôles.

Périmètre des opérations

git switch ne fonctionne qu’avec des branches. Il ne peut pas restaurer des fichiers, désindexer des changements ni extraire des chemins spécifiques depuis d’anciens commits. En bref, il ne prend pas en charge les opérations au niveau fichier.

À l’inverse, git checkout peut agir au niveau fichier. Par exemple, git checkout <commit> -- <file> restaure un fichier spécifique depuis un commit passé.

Cependant, la documentation Git moderne suggère d’utiliser git restore à cet effet. L’essentiel est que git switch exclut volontairement la manipulation de fichiers pour garder un périmètre étroit et prévisible.

Sécurité et désambiguïsation

Un problème courant avec git checkout est l’ambiguïté. Si un nom de branche et un nom de fichier sont identiques, selon le contexte, la commande peut soit changer de branche, soit restaurer un fichier. git switch évite totalement cette ambiguïté. Il n’opère que sur des branches. Si vous ne fournissez pas un nom de branche valide, Git échoue clairement au lieu de deviner.

git switch fournit également une gestion des erreurs plus claire lorsque des modifications locales entrent en conflit avec la branche cible. Si basculer de branche écraserait un travail non validé, Git interrompt l’opération et affiche un message d’erreur explicite, par exemple :

• Si la branche n’existe pas : fatal: invalid reference: feature/login

• Si des modifications locales seraient écrasées : error: Your local changes to the following files would be overwritten by checkout

• Si la branche existe déjà avec -c : fatal: a branch named 'feature/login' already exists

Des messages clairs de ce type réduisent les changements d’état accidentels.

Exemples pratiques avec git switch

Comprendre git switch devient bien plus simple en le voyant à l’œuvre dans de vrais workflows. Ces exemples montrent son comportement au quotidien et expliquent pourquoi il est plus sûr et plus prévisible que git checkout.

Opérations standard sur les branches

Au quotidien, vous passez surtout d’une branche à l’autre ou vous en créez de nouvelles.

• Pour basculer vers une branche locale existante, utilisez : git switch <branch_name>. Git déplace alors HEAD vers la branche indiquée et met à jour votre répertoire de travail en conséquence.

• Pour créer une branche dédiée à une nouvelle fonctionnalité « new_ui » et y basculer en une étape, utilisez git switch -c feature/new-ui. Cela crée la branche depuis votre commit actuel et déplace immédiatement HEAD dessus.

• Si vous devez réinitialiser ou écraser une branche existante, utilisez : git switch -C feature/new-ui. Le -C majuscule force la création ou réinitialise le pointeur de branche. L’intention destructrice est ainsi explicite.

• Vous pouvez aussi alterner rapidement entre vos deux dernières branches avec git switch -. Très pratique pour examiner du code sur une branche et revenir sans cesse à votre branche de fonctionnalité.

Gérer les branches distantes

Il arrive souvent qu’une branche existe sur le dépôt distant mais pas en local. Par exemple, quelqu’un pousse origin/bugfix, mais vous ne l’avez pas encore créée en local.

• Si vous exécutez : git switch bugfix, Git créera une branche locale bugfix et la configurera pour suivre la branche distante origin/bugfix, à condition qu’il y ait une correspondance évidente sur origin. Cela simplifie la collaboration, car vous n’avez pas besoin de configurer manuellement le suivi amont.

• Si vous souhaitez empêcher Git de deviner, utilisez : git switch --no-guess bugfix. Git échoue alors si la branche n’existe pas en local. Utile dans des workflows stricts où le suivi automatique pourrait prêter à confusion.

• Si vous préférez être explicite lors de la création d’une branche de suivi, utilisez git switch -c bugfix --track origin/bugfix. La relation de suivi est alors claire dans la commande elle-même.

Inspection expérimentale de commits

Parfois, vous souhaitez simplement examiner un ancien commit. Peut-être pour tester une version précédente ou vérifier quand un bug a été introduit. Dans ce cas, vous voulez revenir temporairement à ce point de l’historique.

Avec git switch, vous devez le préciser explicitement : git switch --detach <commit-hash>.

L’option --detach indique à Git : déplacez HEAD directement vers ce commit, et non vers une branche. Vous pouvez maintenant explorer le code, lancer des tests ou construire le projet. Si vous créez de nouveaux commits dans cet état, ils ne sont rattachés à aucune branche tant que vous n’en créez pas une.

Avec git checkout <commit-hash>, la même action se produit automatiquement sans option supplémentaire. On entre donc facilement en mode détaché par inadvertance, tandis que l’exigence de --detach avec git switch évite les états de HEAD détachée accidentels.

Intégration de git switch dans les workflows

Voyons maintenant comment intégrer git switch dans des workflows Git typiques.

Choix selon les scénarios

Dans les workflows modernes, git switch devrait couvrir tout le travail lié aux branches, notamment 

• Le développement de fonctionnalités au quotidien
• L’examen des pull requests
• Le rebase en local
• Les scripts CI/CD qui extraient des branches pendant les builds

Parce que git switch se concentre uniquement sur la gestion des branches, il exprime clairement l’intention.

git checkout a toujours un rôle, mais il est désormais plus restreint. De nombreux scripts d’automatisation hérités, écrits avant Git 2.23, s’y appuient encore. Certaines opérations de retour en arrière au niveau fichier peuvent aussi l’utiliser, même si git restore est la solution privilégiée à l’avenir.

Dépannage des erreurs courantes

Deux scénarios distincts peuvent poser problème avec git switch.

« Your local changes would be overwritten »

Un problème fréquent lors d’un changement de branche avec des modifications locales est « error: Your local changes would be overwritten ». Ici, Git bloque l’opération, car le basculement écraserait du travail non validé. Deux options sûres s’offrent à vous :

1. Si vous souhaitez conserver ces changements pour plus tard, exécutez git stash avant de basculer vers la branche cible. Après le basculement, vous pouvez les restaurer avec git stash pop.

2. Si vous voulez délibérément abandonner les changements locaux, utilisez : git switch --discard-changes target-branch. Cette option indique à Git de supprimer les changements locaux et de réinitialiser l’index et l’arborescence de travail pour correspondre à la branche cible (elle ne supprime pas les fichiers non suivis).

Entrer accidentellement en état de HEAD détachée

Autre scénario : vous vous retrouvez par erreur en état de HEAD détachée. Si vous réalisez que vous n’êtes pas sur une branche mais souhaitez conserver votre travail, créez immédiatement une nouvelle branche : git switch -c recovery-branch. Cela rattache votre historique de commits actuel à une branche nommée et préserve vos changements.

Bonnes pratiques pour adopter git switch

Adopter git switch n’est pas qu’une préférence de commande. C’est une petite évolution structurelle de la manière dont les équipes pensent leurs workflows Git. Les bénéfices s’accumulent lorsque l’adoption est cohérente dans la documentation, l’onboarding et l’automatisation.

Stratégies de migration d’équipe

Commencez par votre documentation interne. Si vos guides « Pour bien démarrer » enseignent encore git checkout pour changer de branche, mettez-les à jour avec git switch. Ne conservez checkout que là où il est réellement nécessaire.

La formation joue aussi un rôle. Modernes Git commands provident des messages d’erreur plus clairs, en particulier lorsque des changements locaux entrent en conflit avec un changement de branche. Encouragez les développeurs à lire et à comprendre ces messages plutôt que de les considérer comme des échecs génériques. Le jeu de commandes plus récent est plus explicite : le reconnaître renforce la confiance et réduit les erreurs.

Cohérence dans l’automatisation

Dans les scripts shell, les pipelines CI et les alias Git, privilégiez git switch pour la navigation entre branches, car l’intention est immédiate. Un script qui utilise git switch main est plus facile à interpréter qu’un script qui s’appuie sur git checkout, susceptible d’avoir plusieurs sens.

Si vous définissez des alias Git, mettez-les à jour pour refléter les usages modernes. Par exemple, un alias de création de branches de fonctionnalité devrait encapsuler git switch -c, et non git checkout -b.

Enfin, vérifiez les versions de Git dans tous les environnements. git switch requiert Git 2.23 ou supérieur. Assurez-vous que les machines des développeurs, les runners CI et les serveurs de build répondent à cette exigence avant de standardiser la nouvelle commande. Un simple contrôle de version évite des problèmes de compatibilité subtils.

Conclusion

Avec un peu de recul, l’avantage majeur de git switch est simple. Il rend la gestion des branches plus claire, plus sûre et plus intentionnelle. Quand vous exécutez la commande, il n’y a aucune ambiguïté sur ce qu’elle fait. Vous changez de branche. Point. Et ce petit surcroît de clarté lève une quantité surprenante de frictions dans le développement au quotidien.

Cependant, git checkout n’a pas été déprécié ; vous pouvez toujours l’utiliser pour restaurer des fichiers, passer entre des branches ou gérer des scénarios plus complexes. Mais pour la navigation quotidienne entre branches, Git vous encourage à utiliser git switch.

Pour aller plus loin, je vous recommande notre cours Intermediate Git, centré sur la collaboration avec Git.