Introduction

L'index, aussi appelé staging area ou cache, est l'une des caractéristiques distinctives de Git. C'est un fichier binaire situé à .git/index qui contient l'arbre que vous comptez commiter ensuite. Comprendre l'index dissipe l'essentiel du mystère de la sortie de git status.

Pourquoi il existe

L'index vous permet de composer un commit délibérément plutôt que de tout balancer en bloc. Vous pouvez éditer dix fichiers mais ne commiter que les trois qui corrigent un bug, en laissant les autres stagés pour un commit ultérieur. Ce découplage permet un historique propre et atomique.

Inspecter l'index

Deux commandes comparent les trois zones :

git diff             # arborescence de travail vs index
git diff --staged    # index vs HEAD
git diff HEAD        # arborescence de travail vs HEAD

La commande de plomberie git ls-files --stage montre le contenu brut de l'index, y compris les hachages SHA-1 :

git ls-files --stage

Stager des changements

git add file.txt          # ajouter ou mettre à jour
git add .                 # tout ajouter depuis le répertoire courant
git add -u                # mettre à jour seulement les fichiers suivis
git add -p                # interactif hunk par hunk
git add -N new.txt        # intent-to-add (suivre vide)

Désindexer (unstage)

Si vous avez stagé quelque chose par erreur, retirez-le sans perdre l'édition :

# Moderne (Git 2.23+)
git restore --staged file.txt

# Syntaxe ancienne, fonctionne toujours
git reset HEAD file.txt

L'index lors des conflits

Pendant un conflit de merge, l'index gagne trois entrées par chemin en conflit : le stage 1 est l'ancêtre commun, le stage 2 est « ours », le stage 3 est « theirs ». git ls-files -u les affiche :

git ls-files -u

Résoudre le conflit signifie écrire une version finale et la git add, ce qui fait revenir à une seule entrée stage 0.

Le format du fichier index

L'index est un format binaire documenté dans les sources de Git sous Documentation/gitformat-index.txt. Il commence par un en-tête de 12 octets (signature DIRC, version, nombre d'entrées) suivi d'entrées triées. Plusieurs extensions optionnelles ajoutent du caching : TREE met en cache les hachages de sous-arbres pour un write-tree rapide, et UNTR met en cache la liste des fichiers non suivis pour un git status rapide. Git moderne supporte aussi un index sparse qui élide les entrées en dehors du cône que vous avez extrait :

git sparse-checkout init --cone
git config core.sparseCheckoutCone true
git update-index --test-untracked-cache

Erreurs fréquentes

Croire que git add est définitif. Ce n'est pas le cas : vous pouvez stager, éditer encore, et restager. L'index n'est que le brouillon du prochain commit. Autre confusion classique : éditer un fichier stagé, puis commiter, et être perplexe que les nouvelles éditions ne soient pas incluses. git add capture un instantané au moment où vous l'exécutez ; les éditions ultérieures vivent uniquement dans l'arborescence de travail. Exécutez git diff (sans flag) pour voir ce qui est stagé-puis-modifié. Enfin, ne supprimez jamais .git/index manuellement ; reconstruisez-le avec git read-tree HEAD s'il est jamais corrompu.