git add

Description

La commande git add ajoute les modifications du répertoire de travail à la zone de transit (aussi appelée l'index). Elle permet d'indiquer à Git quelles modifications vous souhaitez inclure dans le prochain commit. git add ne sauvegarde rien dans l'historique par elle-même — elle marque simplement les modifications comme prêtes. Pour les enregistrer effectivement, il faut ensuite exécuter git commit. Pour vérifier ce qui est en transit ou non à tout moment, utilisez git status.

Cette page explique ce que fait git add, les trois « zones » Git entre lesquelles elle opère, ses options les plus utiles, ainsi que les modes interactif et d'édition de patches pour mettre en transit des modifications morceau par morceau.

Les trois zones

Chaque modification dans un projet Git passe par trois zones :

• Répertoire de travail — les fichiers que vous éditez réellement sur le disque.
• Zone de transit (index) — un instantané de ce qui ira dans le prochain commit.
• Dépôt — l'historique des commits, écrit par git commit.

git add déplace les modifications du répertoire de travail vers la zone de transit. git commit écrit ensuite tout ce qui est en transit dans le dépôt. Ce flux en deux étapes est ce qui vous permet de diviser un répertoire de travail désordonné en commits propres et ciblés.

Pourquoi mettre des modifications en transit ?

Dans de nombreux systèmes de contrôle de version, valider un commit capture tout ce que vous avez modifié. Git ajoute délibérément la zone de transit entre les deux afin que vous puissiez décider exactement ce que chaque commit contient. Cela est utile lorsque vous avez modifié plusieurs éléments sans rapport les uns avec les autres : vous pouvez mettre en transit et valider une modification logique, puis mettre en transit et valider la suivante, en gardant un historique lisible.

Étant donné que la mise en transit capture un instantané au moment où vous l'exécutez, git add doit être relancé chaque fois que vous effectuez d'autres modifications à inclure. Si vous mettez un fichier en transit puis continuez à le modifier, les modifications ultérieures restent hors transit jusqu'à ce que vous exécutiez git add à nouveau.

Options courantes

Mettre un seul fichier en transit pour le prochain commit :

git add <file>

Mettre en transit toutes les modifications dans un répertoire (récursivement, y compris les nouveaux fichiers) :

git add <directory>

Mettre en transit toutes les modifications dans le dépôt entier — fichiers nouveaux, modifiés et supprimés :

git add -A

Mettre en transit les modifications des fichiers déjà suivis uniquement, y compris les suppressions, mais ignorer les nouveaux fichiers non suivis :

git add -u

Mettre en transit les modifications de façon interactive, en choisissant des portions de fichiers morceau par morceau :

git add -p

git add . vs git add -A vs git add -u

Ces trois formes sont faciles à confondre, il convient donc d'être précis :

Dans les versions modernes de Git, git add . et git add -A mettent tous deux les suppressions en transit ; la différence porte uniquement sur la portée du chemin. Utilisez -u lorsque vous avez créé des fichiers temporaires que vous ne souhaitez pas valider et que vous préférez ne pas les lister dans .gitignore.

Exemples de git add

Vous pouvez exécuter ces commandes dans n'importe quel dépôt Git. Commencez par vérifier l'état actuel avec git status, puis mettez en transit et validez.

Mettre en transit un nouveau fichier

git add hello.py

Mettre en transit plusieurs fichiers spécifiques à la fois

git add hello.py utils.py README.md

Tout mettre en transit, puis valider avec un message

git add -A
git commit -m "Add greeting script"

Voir ce qui est en transit avant de valider

git status

On branch main
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        new file:   hello.py

Pour retirer un fichier de la zone de transit sans perdre vos modifications, utilisez git restore --staged (ou, dans les anciennes versions de Git, git reset) :

git restore --staged hello.py

Mode interactif

L'exécution de git add -p (ou la sélection de l'option patch depuis git add -i) démarre une session de mise en transit interactive. Git vous montre un hunk — un bloc de lignes modifiées — à la fois et vous invite à saisir une commande. Les réponses les plus courantes sont :

• y - mettre ce hunk en transit
• n - ne pas mettre ce hunk en transit
• q - quitter ; ne pas mettre ce hunk ni les suivants en transit
• a - mettre ce hunk et tous les hunks suivants du fichier en transit
• d - ne pas mettre ce hunk ni les hunks suivants du fichier en transit
• g - sélectionner un hunk vers lequel aller
• / - rechercher un hunk correspondant à l'expression régulière donnée
• j - laisser ce hunk non décidé, passer au prochain hunk non décidé
• J - laisser ce hunk non décidé, passer au hunk suivant
• k - laisser ce hunk non décidé, revenir au hunk non décidé précédent
• K - laisser ce hunk non décidé, revenir au hunk précédent
• s - diviser le hunk courant en hunks plus petits
• e - éditer manuellement le hunk courant
• ? - afficher l'aide

La division (s) est particulièrement pratique : si Git présente deux modifications sans rapport comme un seul hunk, s les sépare afin que vous puissiez mettre en transit uniquement la partie souhaitée. C'est la méthode habituelle pour construire un commit propre à partir d'un fichier contenant des modifications mixtes.

Édition de patches

L'appel de git add -e ou la sélection de e depuis le sélecteur de chunks interactif ouvre un patch dans votre éditeur. Après avoir quitté l'éditeur, la sortie est appliquée à l'index. Vous pouvez apporter des modifications arbitraires au patch, mais certaines éditions peuvent produire des sorties complexes, voire rendre le patch inapplicable. Si vous souhaitez annuler entièrement l'opération, supprimez simplement toutes les lignes du patch. Voici quelques éléments courants que vous pouvez rencontrer dans un patch, et les opérations d'édition qui ont du sens pour chacun.

Les lignes commençant par + représentent du contenu ajouté. Vous pouvez les supprimer pour éviter de mettre en transit les lignes ajoutées.

Les lignes commençant par - représentent du contenu supprimé. Pour éviter de mettre en transit leur suppression, vous pouvez convertir le - en espace ( ).

Le contenu modifié est affiché avec des lignes - (supprimant l'ancien contenu) suivies de lignes + (ajoutant le contenu de remplacement). Pour éviter de mettre en transit la modification, convertissez les lignes - en espaces et supprimez les lignes +. Notez que modifier seulement la moitié de la paire peut entraîner des modifications confuses dans l'index.

Pièges courants

• La mise en transit est un instantané, pas un lien en direct. Si vous faites git add sur un fichier puis le modifiez à nouveau, seule la version antérieure est en transit. Exécutez git add une nouvelle fois pour inclure les nouvelles modifications — git status affichera le même fichier à la fois sous « Changes to be committed » et « Changes not staged for commit ».
• git add ne supprime pas les fichiers pour vous. Il met en transit les suppressions de fichiers déjà suivis (avec -A ou -u), mais pour supprimer un fichier du disque et mettre cette suppression en transit en une seule étape, utilisez git rm.
• Les fichiers ignorés restent ignorés. Les motifs dans .gitignore ne sont pas mis en transit par git add .. Pour forcer l'ajout d'un fichier ignoré, utilisez git add -f <file>.
• Rien n'est encore permanent. La mise en transit est entièrement réversible. Utilisez git restore --staged <file> pour retirer de la zone de transit avant de faire un commit.

Pratique