Git add et staging : préparer exactement le prochain commit

Répertoire de travail, index et commit

git add n’écrit rien dans votre historique. Il copie le contenu actuel d’un fichier dans l’index, aussi appelé zone de staging, et git commit construit le prochain commit à partir de cet index, pas à partir des fichiers de votre disque. Le staging sert à choisir ce qui entre dans un commit et ce qui attend.

Trois emplacements entrent en jeu :

Les exemples ci-dessous utilisent un dépôt jetable nommé orbit-api, qui contient un commit. Depuis, vous avez modifié un fichier suivi, src/search.ts, pour masquer les projets archivés dans les résultats de recherche, et vous avez créé un nouveau fichier, scripts/seed.ts. Les sorties sont celles de Git 2.23, en anglais ; Git 2.30 et 2.54 affichent le même texte pour chaque commande de ce guide. Voici ce que Git rapporte :

git status

On branch main
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:   src/search.ts

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

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

Rien n’est encore indexé. src/search.ts est suivi et diffère de l’index. scripts/seed.ts n’est pas suivi : Git ne le connaît pas, donc il liste le dossier scripts/ plutôt que le fichier. Un git commit à ce stade n’aurait rien à enregistrer.

Un détail comptera plus loin. git add capture le fichier tel qu’il est à cet instant. Si vous le modifiez encore ensuite, ces nouvelles modifications restent dans le répertoire de travail, hors du commit, jusqu’à ce que vous relanciez git add sur ce fichier.

Ajouter des fichiers avec git add

Pour indexer les changements d’un fichier, nommez-le, puis demandez l’état court :

git add src/search.ts
git status -s

M  src/search.ts
?? scripts/

Le format court a deux colonnes. La première décrit l’index, la seconde le répertoire de travail. Avant le git add, la même commande affichait M src/search.ts, avec la lettre dans la seconde colonne : modifié, non indexé. Maintenant la lettre est dans la première colonne : indexé. ?? désigne toujours le dossier non suivi.

La forme longue décrit le même état avec des noms de sections :

git status

On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	modified:   src/search.ts

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

Changes to be committed correspond à l’index. Changes not staged for commit et Untracked files décrivent le répertoire de travail. L’indication sous la première section est la commande que vous utiliserez pour retirer un fichier de l’index, ce que vous verrez plus bas.

Pour tout indexer d’un coup, nouveaux fichiers compris, utilisez git add -A :

git add -A
git status -s

A  scripts/seed.ts
M  src/search.ts

scripts/seed.ts est maintenant A : ajouté à l’index. Depuis la racine du dépôt, git add . donne le même résultat. Les deux commandes diffèrent dans un sous-dossier. Lancé depuis src/, git add . n’indexe que ce qui a changé sous src/, alors que git add -A indexe tout le répertoire de travail. git add -u est plus restreint : il indexe les changements des fichiers suivis et ignore les nouveaux.

Les suppressions comptent aussi comme des changements. Après avoir supprimé un fichier suivi, git add -A indexe la suppression, et git status -s l’affiche par un D dans la première colonne.

Aucune de ces commandes ne demande de confirmation. Lisez git status avant d’utiliser les formes larges, sinon vous risquez d’indexer un fichier que vous vouliez laisser de côté.

Vérifier ce qui sera réellement commité

git diff --cached montre l’index comparé à HEAD : exactement ce que git commit enregistrerait. --staged en est un synonyme.

git diff --cached

diff --git a/scripts/seed.ts b/scripts/seed.ts
new file mode 100644
index 0000000..609fd8a
--- /dev/null
+++ b/scripts/seed.ts
@@ -0,0 +1,3 @@
+import { buildIndex } from "../src/search";
+
+export const demo = buildIndex([]);
diff --git a/src/search.ts b/src/search.ts
index 24c85be..d0cb9d6 100644
--- a/src/search.ts
+++ b/src/search.ts
@@ -23,5 +23,7 @@ export function search(index: Map<string, Project[]>, query: string): Project[]
       hits.set(project.id, project);
     }
   }
-  return [...hits.values()].sort((a, b) => a.name.localeCompare(b.name));
+  return [...hits.values()]
+    .filter((hit) => !hit.archived)
+    .sort((a, b) => a.name.localeCompare(b.name));
 }

Chaque fichier a un en-tête, suivi d’un ou plusieurs blocs qui commencent par @@. Les lignes qui commencent par + sont ajoutées, celles qui commencent par - sont supprimées, et les lignes sans marque sont du contexte. Le guide de git diff --staged détaille la lecture de ces lignes.

Un simple git diff compare le répertoire de travail à l’index, et il n’affiche rien ici parce que tout est déjà indexé. S’il affiche quelque chose après un git add, le fichier a des changements aux deux endroits, ce que git status -s montre par MM. Pour n’indexer qu’un bloc d’un tel fichier, utilisez git add -p.

Préparer des changements séparés

Un commit se lit mieux quand il porte une seule idée. Le correctif de recherche et le script d’amorçage sont deux idées : retirez donc le script de l’index.

git restore --staged scripts/seed.ts
git status -s

M  src/search.ts
?? scripts/

Le fichier reste sur le disque, intact. git restore --staged le retire seulement de l’index, ce qui le rend de nouveau non suivi. Pour vider l’index d’un seul coup, lancez git restore --staged . depuis la racine du dépôt : tous les fichiers quittent l’index et gardent leurs modifications dans le répertoire de travail. Git 2.23, la version utilisée pour ces exemples, inclut déjà cette commande, et git status la suggère dès que quelque chose est indexé.

Commitez maintenant le correctif :

git commit -m "Hide archived projects from search results"

[main 3735e86] Hide archived projects from search results
 1 file changed, 3 insertions(+), 1 deletion(-)

Puis indexez le script, commitez-le et listez l’historique :

git add scripts/seed.ts
git commit -m "Add a seed script"
git log --oneline

[main c7aeb19] Add a seed script
 1 file changed, 3 insertions(+)
 create mode 100644 scripts/seed.ts
c7aeb19 Add a seed script
3735e86 Hide archived projects from search results
f96f13a Add project search

Vos identifiants de commit seront différents de ceux-ci. Le résultat : deux commits, chacun avec un seul but.

Trois situations se présentent juste après. Si vous avez oublié un fichier ou fait une faute dans le message, corrigez le dernier commit. Si un commit existe déjà et que vous voulez voir ce qu’il contient, le guide de git show explique sa sortie. Et si vous voulez réordonner, fusionner ou reformuler plusieurs commits avant de les partager, passez par un rebase interactif.

Passer du terminal à une vue graphique

GitMini affiche le même état sans rien taper. Après les modifications ci-dessus, sélectionnez la ligne // WIP du graphe : le panneau de droite liste src/search.ts et scripts/seed.ts sous Unstaged. La section Staged affiche « Nothing staged ». GitMini liste le nouveau fichier par son propre chemin, scripts/seed.ts, avec un badge U pour « non suivi », tandis qu’un fichier modifié comme src/search.ts reçoit un M. Les libellés de l’interface restent en anglais ci-dessous.

Indexez src/search.ts et la ligne passe dans Staged. Le formulaire de commit, sous les listes, demande un résumé : un champ Summary (required) et une description facultative. Le bouton affiche Commit 1 file. Il reste désactivé, avec une infobulle comme « No staged files » ou « Enter Summary », tant qu’aucun résumé n’est saisi ou qu’aucun fichier n’est indexé. Indexez ensuite scripts/seed.ts et faites le second commit de la même façon.

Faites attention à Discard all et à Discard changes, placés près des boutons d’indexation. Ce ne sont pas des actions de désindexation : elles jettent les modifications, GitMini prévient qu’elles ne peuvent pas être restaurées depuis l’application, et les fichiers non suivis sont supprimés du disque.

Sources

• Documentation Git : git-add (en anglais), consulté le 4 octobre 2026.
• Documentation Git : git-diff (en anglais), consulté le 4 octobre 2026.
• Pro Git : Indexation interactive, consulté le 4 octobre 2026.
• README du produit GitMini, consulté le 4 octobre 2026.