Comment gérer l'erreur 'error: untracked working tree files would be overwritten by checkout' dans Git

Introduction

Git est un système de contrôle de version puissant, essentiel au développement logiciel moderne. Lors de l'utilisation de Git, vous pourriez rencontrer le message d'erreur : "error: untracked working tree files would be overwritten by checkout". Cette erreur se produit lorsque vous essayez de changer de branche, mais Git détecte que cette action écraserait des fichiers dans votre répertoire de travail actuel qui ne sont pas encore suivis par Git. Cette fonctionnalité de sécurité empêche la perte accidentelle de données.

Dans ce laboratoire, vous apprendrez la cause de cette erreur courante, comment identifier les fichiers en conflit et plusieurs méthodes pour la résoudre. À la fin de ce tutoriel, vous serez en mesure de gérer votre flux de travail Git plus efficacement et de traiter cette erreur en toute confiance.

Réplication de l'erreur de checkout

Pour comprendre comment résoudre l'erreur, nous devons d'abord la reproduire. Cela aidera à clarifier pourquoi Git signale un conflit. Notre script d'installation a déjà créé un dépôt Git avec deux branches : main et feature-branch. La feature-branch contient un fichier que nous allons maintenant créer localement dans la branche main.

Tout d'abord, naviguez jusqu'au répertoire du projet. Toutes les commandes de ce laboratoire seront exécutées à partir de ce répertoire.

cd ~/project/git-checkout-demo

Vérifions le statut actuel de notre dépôt pour nous assurer que tout est propre.

git status

La sortie devrait être :

On branch main
nothing to commit, working tree clean

Cela confirme que nous sommes sur la branche main sans changements en attente. Maintenant, listons les branches disponibles.

git branch

Vous verrez les deux branches, avec * indiquant la branche actuelle :

  feature-branch
* main

Maintenant, créons le conflit. Nous allons créer un nouveau fichier nommé feature.md dans notre répertoire de travail actuel. Ce fichier est actuellement "non suivi" (untracked) par Git sur la branche main, mais un fichier portant le même nom existe déjà et est suivi sur feature-branch.

echo "## My local changes to feature documentation" > feature.md

Vérifiez à nouveau le statut pour voir le nouveau fichier non suivi.

git status

La sortie montre maintenant feature.md comme un fichier non suivi :

On branch main
Untracked files:
  (use "git add <file>..." to include in what will be committed)
	feature.md

nothing added to commit but untracked files present (use "git add" to track)

Enfin, tentons de basculer vers la feature-branch.

git checkout feature-branch

Cette commande échouera et produira l'erreur que nous étudions :

error: The following untracked working tree files would be overwritten by checkout:
	feature.md
Please move or remove them before you switch branches.
Aborting

Git a annulé le checkout pour protéger votre fichier local non suivi feature.md contre l'écrasement par la version de feature-branch. Dans les étapes suivantes, nous explorerons différentes façons de résoudre ce problème.

Résolution du conflit avec git stash

L'une des méthodes les plus sûres et les plus courantes pour résoudre cette erreur est d'utiliser git stash. Cette commande enregistre temporairement vos modifications locales (à la fois celles qui sont préparées et celles qui ne le sont pas) et ramène le répertoire de travail à l'état du dernier commit. Cela vous permet de changer de branche librement.

Nous sommes actuellement sur la branche main avec le fichier non suivi feature.md qui cause le conflit.

Pour mettre en stash les fichiers non suivis, vous devez utiliser l'option --include-untracked (ou -u).

git stash push --include-untracked

Vous verrez un message de confirmation :

Saved working directory and index state WIP on main: <commit_hash> Initial commit with README

Vérifiez maintenant à nouveau le statut de votre dépôt.

git status

Le répertoire de travail est propre, et le fichier non suivi a disparu :

On branch main
nothing to commit, working tree clean

Avec le répertoire de travail propre, vous pouvez maintenant basculer vers la feature-branch sans aucune erreur.

git checkout feature-branch

La commande réussira :

Switched to branch 'feature-branch'

Vous êtes maintenant sur la feature-branch. Si vous inspectez feature.md, vous verrez la version qui appartient à cette branche.

cat feature.md

## Official Feature Documentation

Vos modifications locales sont stockées en toute sécurité dans le stash. Pour les récupérer, vous pouvez revenir à la branche main et appliquer le stash.

git checkout main
git stash pop

La commande git stash pop réapplique les modifications mises en stash et les supprime de la liste des stashes. Votre fichier feature.md est maintenant de retour dans votre répertoire de travail.

Pour l'étape suivante, assurons-nous de revenir à l'état de conflit. Si vous avez suivi la commande git stash pop, vous y êtes déjà.

Résolution du conflit avec git clean

Une autre façon de résoudre le conflit est de supprimer les fichiers non suivis. Cette méthode convient uniquement lorsque vous êtes certain de ne pas avoir besoin des fichiers non suivis. La commande git clean est utilisée à cette fin.

Attention : Cette commande supprime définitivement les fichiers, utilisez-la donc avec prudence.

Tout d'abord, assurons-nous d'être dans l'état de conflit sur la branche main avec le fichier non suivi feature.md.

cd ~/project/git-checkout-demo
git checkout main
## If feature.md doesn't exist, recreate it
if [ ! -f "feature.md" ]; then echo "## My local changes" > feature.md; fi
git status

Avant de supprimer quoi que ce soit, il est recommandé d'effectuer un "essai à blanc" (dry run) en utilisant l'indicateur -n. Cela vous montrera quels fichiers seraient supprimés sans les supprimer réellement.

git clean -n

La sortie listera les fichiers à supprimer :

Would remove feature.md

Une fois que vous avez confirmé que vous souhaitez supprimer ces fichiers, vous pouvez exécuter à nouveau la commande avec l'indicateur -f (force).

git clean -f

Git confirmera la suppression :

Removing feature.md

Maintenant que le fichier non suivi a disparu, votre répertoire de travail est propre et vous pouvez changer de branche sans problème.

git checkout feature-branch

Le checkout réussira.

Switched to branch 'feature-branch'

Cette méthode est rapide mais destructive. La méthode git stash de l'étape précédente est généralement plus sûre car elle préserve votre travail.

Résolution en suivant le fichier et bonnes pratiques

Parfois, le fichier non suivi n'est pas jetable ; c'est un travail que vous souhaitez conserver. Dans ce cas, l'approche correcte consiste à ajouter le fichier au système de suivi de Git en le committant. Cette section couvre également les bonnes pratiques pour éviter que cette erreur ne se produise en premier lieu.

Tout d'abord, revenons à la branche main et recréons notre fichier conflictuel.

cd ~/project/git-checkout-demo
git checkout main
echo "## My local changes to feature documentation" > feature.md

Méthode : Suivre le fichier

Si le fichier non suivi est important, vous devez le committer sur la branche actuelle.

1. Ajoutez le fichier à la zone de staging.

   git add feature.md

2. Commitez le fichier préparé.

   git commit -m "Add local version of feature.md"

Maintenant que vos modifications sont sauvegardées en toute sécurité sur la branche main, Git peut gérer le changement. Lorsque vous checkout la feature-branch, Git remplacera simplement le fichier de l'espace de travail par la version de cette branche.

git checkout feature-branch

Le checkout est réussi. Vos modifications committées sont en sécurité dans l'historique de la branche main.

Bonne pratique : Utiliser .gitignore

Pour empêcher que certains fichiers (comme les journaux, les artefacts de build ou les fichiers d'environnement) ne soient jamais suivis, vous devez utiliser un fichier .gitignore. Git ignorera tous les fichiers ou répertoires correspondant aux motifs dans .gitignore, les empêchant de devenir des fichiers non suivis conflictuels.

Créons un fichier .gitignore pour ignorer tous les fichiers .log.

## Revenir à main pour ajouter le fichier .gitignore
git checkout main

## Créer le fichier .gitignore
echo "*.log" > .gitignore

Maintenant, créez un fichier journal.

touch app.log

Vérifiez le statut.

git status

Remarquez que app.log n'apparaît pas comme un fichier non suivi. Cependant, le fichier .gitignore lui-même est non suivi.

On branch main
Untracked files:
  (use "git add <file>..." to include in what will be committed)
	.gitignore

nothing added to commit but untracked files present (use "git add" to track)

Vous devriez toujours committer votre fichier .gitignore afin que les règles soient partagées sur l'ensemble du projet.

git add .gitignore
git commit -m "Add .gitignore to ignore log files"

En committant fréquemment et en utilisant .gitignore efficacement, vous pouvez réduire considérablement les risques de rencontrer cette erreur de checkout.

Résumé

Dans ce laboratoire, vous avez appris à diagnostiquer et à résoudre l'erreur "error: untracked working tree files would be overwritten by checkout" dans Git.

Vous avez accompli les actions suivantes :

1. Réplication de l'erreur : Vous avez réussi à créer un scénario qui déclenche l'erreur, vous donnant une compréhension claire de sa cause.
2. Résolution avec git stash : Vous avez appris à utiliser git stash pour sauvegarder temporairement les fichiers non suivis, vous permettant de changer de branche en toute sécurité sans perdre votre travail.
3. Résolution avec git clean : Vous avez appris à utiliser git clean pour supprimer les fichiers non suivis lorsqu'ils ne sont plus nécessaires, après avoir d'abord effectué un essai à blanc pour éviter les erreurs.
4. Résolution en suivant les fichiers : Vous avez appris à résoudre le problème en committant le fichier non suivi, ce qui est l'approche correcte pour le travail que vous avez l'intention de conserver.
5. Apprentissage des bonnes pratiques : Vous avez appris à utiliser un fichier .gitignore pour empêcher les fichiers temporaires ou liés à la compilation de causer des conflits.

En maîtrisant ces techniques, vous pouvez maintenir un flux de travail Git plus propre et plus efficace, et gérer avec confiance l'un des problèmes les plus courants rencontrés par les développeurs.