git status

La commande git status répond à une seule question, constante tout au long de votre travail : qu'est-ce qui a changé depuis mon dernier commit, et qu'est-ce qui est prêt à être commité ? C'est la commande que vous exécutez plus que toute autre — avant de préparer des fichiers, avant de commiter, et chaque fois que vous perdez le fil de l'état d'un fichier. Cette page explique les trois états dans lesquels un fichier peut se trouver, comment lire les sorties longue et courte, et les options qui permettent d'utiliser status dans des scripts.

Ce que git status affiche

git status affiche l'état de deux choses : le répertoire de travail (les fichiers sur le disque que vous modifiez) et la zone de préparation (staging area), aussi appelée l'index (l'instantané que vous préparez pour le prochain commit). Elle vous indique quels fichiers sont :

• Préparés (staged) — les modifications ajoutées avec git add et prêtes pour le prochain commit.
• Non préparés (modified) — les fichiers suivis que vous avez modifiés mais pas encore ajoutés.
• Non suivis (untracked) — les nouveaux fichiers que Git n'a jamais vus et ne suit pas.

Ce que git status ne montre pas, c'est l'historique des commits. Elle ne dit rien sur les commits précédents, les branches fusionnées, ou qui a modifié quoi — pour cela, utilisez git log. Elle ne montre pas non plus le contenu de vos modifications ; pour voir les lignes exactes ajoutées et supprimées, utilisez git diff. En résumé, status résume l'effet de git add et de git commit sur vos fichiers actuels.

Utilisation de base

La commande ne prend aucun argument dans sa forme la plus courante :

git status

Dans un dépôt propre sans rien à faire, Git vous le signale :

On branch master
nothing to commit, working tree clean

Lire la sortie longue

La sortie par défaut (également accessible avec --long) est le format verbeux et lisible par les humains. Suivez un fichier tout au long de son cycle de vie pour voir chaque section apparaître.

Un tout nouveau fichier que Git n'a jamais vu est non suivi :

On branch master

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	w3docs.txt

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

Après git add w3docs.txt, le même fichier passe sous Changes to be committed — il est maintenant préparé (staged) :

On branch master

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
	new file:   w3docs.txt

Une fois que vous faites git commit, l'arbre de travail est à nouveau propre. Modifiez maintenant w3docs.txt et créez un second fichier new.txt. Un fichier suivi que vous modifiez apparaît sous Changes not staged for commit, tandis que le nouveau fichier reste sous Untracked files :

On branch master
Changes 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:   w3docs.txt

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	new.txt

no changes added to commit (use "git add" and/or "git commit -a")

Notez que les indications entre parenthèses sont des suggestions réelles et exécutables : Git vous dit comment déprépareer, annuler ou ajouter à chaque étape.

Le format court

Une fois que vous connaissez la signification des sections, le format long devient encombrant. L'option -s (ou --short) condense tout en une ligne par fichier :

git status -s

Pour l'état ci-dessus (un fichier suivi modifié, un nouveau fichier non suivi), la commande affiche :

 M w3docs.txt
?? new.txt

Chaque entrée comporte un code de statut à deux colonnes. La colonne de gauche correspond à la zone de préparation (l'index) et la colonne de droite correspond à l'arbre de travail :

Un espace en tête signifie « aucun changement dans cette colonne ». Ainsi, M signifie modifié mais non préparé, M signifie que la modification est préparée, et MM signifie une modification préparée plus d'autres modifications non préparées sur le même fichier.

Ajoutez -b pour afficher également la branche actuelle et ses informations de suivi :

git status -sb

## master
 M w3docs.txt
?? new.txt

Sortie pour les scripts : --porcelain

Si vous souhaitez lire git status depuis un script, ne parsez pas le format court ou long — les deux peuvent changer entre les versions de Git et sont affectés par la configuration de l'utilisateur. Utilisez plutôt --porcelain. Il garantit un format stable et lisible par les machines :

git status --porcelain

 M w3docs.txt
?? new.txt

Les colonnes utilisent les mêmes codes à deux caractères que le format court, mais le format est contractuellement stable, ce qui le rend sûr pour les hooks, les vérifications CI et les invites shell. Associez-le à -z pour terminer chaque entrée avec un octet NUL au lieu d'un saut de ligne, ce qui permet de traiter sans ambiguïté les noms de fichiers contenant des espaces ou des sauts de ligne.

Afficher les fichiers ignorés

Par défaut, git status masque les fichiers correspondant à vos règles .gitignore — les artefacts de build et les fichiers binaires tels que .pyc, .obj, .exe, ou les fichiers journaux noieraient sinon les vraies modifications. Pour confirmer qu'un fichier est ignoré (plutôt que simplement oublié), ajoutez --ignored :

git status --ignored

Avec un .gitignore contenant *.log et un fichier debug.log sur le disque, une section supplémentaire apparaît :

Ignored files:
  (use "git add -f <file>..." to include in what will be committed)
	debug.log

C'est le moyen le plus rapide de déboguer une règle d'exclusion qui correspond à plus — ou moins — que prévu.

Options courantes

Pourquoi vérifier le statut souvent

Il est recommandé d'exécuter git status avant chaque git add et git commit. Une vérification rapide évite les erreurs courantes : commiter un fichier que vous avez oublié de préparer, préparer accidentellement un fichier de débogage, ou commiter sur la mauvaise branche. Comme status ne fait que lire le dépôt sans jamais rien modifier, l'exécuter est toujours sans risque.

Une fois que vous avez lu le statut, les étapes naturelles suivantes consistent à inspecter les modifications exactes avec git diff, à annuler une erreur de préparation avec git reset, ou, si vous n'avez pas encore commencé, à créer le dépôt avec git init.

Pratique