git clean

Ce que fait git clean

La commande git clean supprime les fichiers non suivis de votre répertoire de travail. Un fichier non suivi est un fichier qui existe sur le disque mais que Git ne suit pas encore, c'est-à-dire qu'il n'a jamais été ajouté avec git add et n'est pas dans l'index.

Cela distingue git clean de ses voisines parmi les commandes d'annulation :

• git reset déplace le pointeur de branche et peut désindexer des modifications suivies.
• git checkout restaure les fichiers suivis à un état antérieur.
• git clean supprime les fichiers que Git ne suit pas du tout.

Ensemble, elles couvrent l'intégralité de l'arbre de travail : reset/checkout gèrent le contenu suivi et indexé, clean gère le reste. Un usage typique consiste à effacer les artefacts de build, les fichiers générés ou les restes d'expérimentations afin de repartir d'une copie vierge de l'arbre validé.

git clean est irréversible. Cette commande supprime les fichiers directement du système de fichiers, et non dans une zone récupérable comme le stash. Il n'existe pas d'annulation pour git clean. Prévisualisez toujours avec un dry run (-n) en premier.

L'exemple ci-dessous configure un dépôt avec un élément suivi et plusieurs éléments non suivis afin que vous puissiez voir la distinction :

Configurer un dépôt d'exemple

mkdir test_directory
cd test_directory/
git init .
#Initialized empty Git repository in /Users/kev/code/test_directory/.git/
echo "tracked file" > ./test_tracked_file
git add ./test_tracked_file
echo "untracked" > ./test_untracked_file
mkdir ./test_untracked_dir && touch ./test_untracked_dir/file
git status
#On branch master
#No commits yet
#Changes to be committed:
#  (use "git rm --cached <file>..." to unstage)
#        new file:   test_tracked_file
#Untracked files:
#  (use "git add <file>..." to include in what will be committed)
#        test_untracked_dir/
#        test_untracked_file

Après avoir exécuté cela, vous disposez d'un dépôt vierge avec un fichier indexé, test_tracked_file, ainsi qu'un fichier non suivi (test_untracked_file) et un répertoire non suivi (test_untracked_dir). git status les signale dans des sections séparées, exactement la distinction qui intéresse git clean. Tout ce qui suit opère sur ce dépôt.

Pourquoi le forçage est nécessaire

Exécutez la commande seule et Git refuse :

git clean
#fatal: clean.requireForce defaults to true and neither -i, -n, nor -f given; refusing to clean

Comme la suppression est permanente, Git ne s'exécutera pas à moins que vous n'optiez pour -f (forcer), -n (dry run) ou -i (interactif). Vous pouvez modifier le comportement par défaut avec le paramètre git config clean.requireForce, mais le laisser activé est le choix le plus sûr.

Options courantes et utilisation

Le comportement de git clean est contrôlé presque entièrement par quelques options courtes qui se combinent librement.

-n : dry run (prévisualisation)

L'option -n (ou --dry-run) liste ce qui serait supprimé sans rien effacer. Faites-en votre première étape par défaut.

git clean -n
#Would remove test_untracked_file

La sortie nomme test_untracked_file. Notez que le répertoire non suivi n'est pas listé, car par défaut git clean ignore les répertoires (voir -d ci-dessous).

-f : forcer la suppression

L'option -f (ou --force) effectue réellement la suppression. Elle est requise à moins que clean.requireForce ne soit défini à false.

git clean -f
#Removing test_untracked_file

test_untracked_file a maintenant disparu ; un git status ultérieur ne le liste plus. Par défaut, git clean -f agit sur chaque fichier non suivi dans le répertoire courant. Les fichiers correspondant à .gitignore sont laissés intacts, sauf si vous ajoutez -x (voir ci-dessous).

Pour limiter l'opération à un emplacement spécifique, passez un chemin :

git clean -f path/to/dir

-d : inclure les répertoires non suivis

Par défaut, git clean ignore les répertoires non suivis. Ajoutez -d pour les supprimer également. Combinez-le avec -n pour une prévisualisation, puis -f pour confirmer :

git clean -dn
#Would remove test_untracked_dir/
#Would remove test_untracked_file
git clean -df
#Removing test_untracked_dir/
#Removing test_untracked_file

Avec -d, le dry run liste maintenant le répertoire ainsi que le fichier non suivi, et l'exécution forcée supprime les deux, en effaçant le répertoire et tout ce qu'il contient.

-x : inclure les fichiers ignorés

Normalement, git clean respecte .gitignore. L'option -x lui indique de supprimer également les fichiers ignorés, comme node_modules/, les sorties de build, ou les dossiers d'éditeur tels que .idea/. C'est puissant et facile à regretter, donc faites toujours d'abord un dry run.

git clean -xn
#Would remove .idea/
#Would remove build/

-x se combine avec les autres options. La combinaison ci-dessous efface les fichiers non suivis, les répertoires non suivis et les fichiers ignorés en une seule fois, l'équivalent de « réinitialiser ce checkout exactement à ce qui est validé » :

git clean -xdf

Référence rapide

Mode interactif

Si vous n'êtes pas sûr de ce qui doit être supprimé, exécutez git clean en mode interactif avec l'option -i. C'est le moyen le plus sûr de nettoyer un arbre de travail encombré, car rien n'est supprimé tant que vous ne confirmez pas. L'exemple ci-dessous ajoute également -d pour inclure les répertoires. Git affiche les éléments candidats puis une invite What now> proposant six commandes :

git clean -di
#Would remove the following items:
#  test_untracked_dir/ test_untracked_file
#*** Commands ***
#    1: clean                2: filter by pattern    3: select by numbers
#    4: ask each             5: quit                 6: help
#What now>

Voici ce que fait chaque commande.

6 — help. Tapez 6 pour afficher une description de chaque commande :

What now> 6
#clean               - start cleaning files and directories
#filter by pattern   - exclude items from deletion
#select by numbers   - select items to be deleted by numbers
#ask each            - confirm each deletion (like "rm -i")
#quit                - stop cleaning
#help                - this screen
#?                   - help for prompt selection

1 — clean. Supprime les éléments actuellement listés, puis quitte :

What now> 1
#Removing test_untracked_dir/
#Removing test_untracked_file

2 — filter by pattern. Permet d'exclure des éléments par glob. Ici, le motif *_file retire test_untracked_file de la liste de suppression, ne laissant que le répertoire en attente :

What now> 2
#test_untracked_dir/ test_untracked_file
#Input ignore patterns>> *_file
#test_untracked_dir/

3 — select by numbers. Affine la liste par numéro d'élément plutôt que par motif. Git numérote chaque candidat et vous tapez ceux à conserver :

What now> 3
#           1: test_untracked_dir/  2: test_untracked_file
#Select items to delete>>

4 — ask each. Parcourt chaque candidat avec une invite y/N, comme rm -i. Répondez N pour conserver un élément :

What now> 4
#Remove test_untracked_dir/ [y/N]? N
#Remove test_untracked_file [y/N]? N

5 — quit. Quitte le mode interactif sans rien supprimer :

What now> 5
#Bye.

git clean vs stash et reset

git clean ne touche que les fichiers non suivis, donc utilisez-la quand vous souhaitez supprimer du travail plutôt que le sauvegarder. Si vous pensez vouloir récupérer les modifications plus tard, préférez l'une de ces options :

• git stash — met de côté les modifications suivies (et, avec -u, les fichiers non suivis) pour pouvoir les restaurer plus tard. Réversible.
• git reset — déplace le pointeur de branche et désindexe ou supprime les modifications suivies.
• git checkout — restaure les fichiers suivis à leur état validé.

Une réinitialisation complète courante d'un arbre de travail consiste à combiner reset pour le contenu suivi avec clean pour le contenu non suivi :

git reset --hard   # discard tracked changes
git clean -xdf     # remove untracked and ignored files

Après ces deux commandes, le répertoire de travail correspond exactement au dernier commit, sans aucun fichier résiduel d'aucune sorte.

Pratique