git add

Instantanés de base

Ajouter le contenu des fichiers à l’index (zone de préparation)

La commande 'git add' met à jour l’index avec le contenu actuel de l’arbre de travail, pour préparer le contenu du prochain commit. L’index, aussi appelé zone de préparation, sert à préparer le contenu du prochain commit. Quand vous lancez 'git commit' sans autre argument, seules les modifications indexées sont committées. Cette commande peut être lancée plusieurs fois avant un commit pour ajouter des modifications progressivement.

Synopsis

git add [--verbose | -v] [--dry-run | -n] [--force | -f] [--interactive | -i] [--patch | -p] [--all | -A] [--update | -u] [--] [<pathspec>...]
[ ] facultatif| ou<arg> valeur à remplacer... répétable--flag option

Options

Cliquez sur une option pour la déplier

Débutant (4)

Tout indexer d’un coup - tous les nouveaux fichiers, modifications et suppressions de tout votre projet.

Si nécessairePrépare tout, suppressions comprises — vérifiez d’abord git status pour que rien d’indésirable ne se glisse dedans

Exemple

git add -A

N’indexer que les modifications des fichiers que Git connaît déjà. Les nouveaux fichiers non suivis sont ignorés.

Si nécessairePrépare uniquement les modifications des fichiers suivis — pratique quand les nouveaux fichiers ne sont pas encore prêts

Exemple

git add -u

Voir exactement quels fichiers sont indexés pendant l’exécution. Affiche chaque nom de fichier au moment où il est ajouté.

Si nécessaireAffiche chaque fichier au moment où il est préparé ; utile pour les gros add

Exemple

git add -v .

Voir ce qui serait indexé sans rien indexer. Idéal pour vérifier avant de committer.

RecommandéAperçu sans risque de ce qu’un add large préparerait

Exemple

git add -n .

Intermédiaire (5)

Choisir de façon interactive quelles parties d’un fichier indexer. Parfait pour découper de grosses modifications en commits ciblés.

RecommandéRelisez et préparez exactement les hunks qui appartiennent à ce commit

Exemple

git add -p

Ouvrir une interface complète à menus pour gérer l’indexation. Elle permet d’indexer, de désindexer et de relire les modifications de façon interactive.

Si nécessairePréparation par menu ; -p couvre la plupart des besoins plus directement

Exemple

git add -i

Indexer un fichier normalement ignoré par .gitignore. À utiliser quand vous devez passer outre les règles d’exclusion.

Si nécessairePrépare des fichiers ignorés — assurez-vous que le fichier a vraiment sa place dans le dépôt

Exemple

git add -f dist/bundle.js

Noter qu’un fichier sera ajouté plus tard, sans indexer son contenu. Pratique pour voir les nouveaux fichiers dans 'git diff'.

Si nécessaireRend les nouveaux fichiers visibles pour git diff et add -p avant de les préparer

Exemple

git add -N newfile.js

Masquer l’avertissement quand vous ajoutez un dépôt imbriqué (un dossier avec son propre .git) à l’index. À utiliser quand vous voulez vraiment ajouter un dépôt git imbriqué.

DéconseilléEn général, vous voulez plutôt git submodule add qu’un simple dépôt imbriqué

Exemple

git add --no-warn-embedded-repo vendor/library

Avancé (6)

Ouvrir le diff dans votre éditeur avant l’indexation. Vous pouvez choisir à la main les modifications à inclure.

Si nécessaireModifier le diff à la main avant l’indexation ; il est facile de produire un patch qui ne s’applique pas

Exemple

git add -e app.js

Ne pas ajouter de fichiers, seulement rafraîchir leurs infos stat() dans l’index. Nécessite un pathspec. Utile après des changements d’horodatage seuls.

Si nécessaireRafraîchit seulement les infos de fichiers dans l’index ; git status le fait déjà

Exemple

git add --refresh .

Continuer à ajouter des fichiers même si certains échouent. La commande se termine quand même avec un code non nul.

Si nécessaireSaute les fichiers qui ne peuvent pas être ajoutés ; la commande se termine quand même avec un code non nul

Exemple

git add --ignore-errors .

Vérifier si des fichiers seraient ignorés, même s’ils n’existent pas encore. Ne fonctionne qu’avec --dry-run.

Si nécessaireSeulement avec --dry-run : vérifie les règles d’exclusion même pour des chemins absents

Exemple

git add -n --ignore-missing *.tmp

Indexer les fichiers nouveaux et modifiés, mais ignorer les fichiers supprimés de l’arbre de travail. Alias : --ignore-removal. N’a d’effet qu’avec un pathspec (par ex. git add --no-all .).

DéconseilléAncien comportement d’avant la 2.0 qui laisse les suppressions non préparées sans prévenir

Exemple

git add --no-all .

Générer les blocs affichés par -p/-i avec <n> lignes de contexte au lieu des 3 par défaut (ou diff.context). Nécessite Git 2.51 ou plus récent — les versions plus anciennes le rejettent avec "unknown switch `U'".

Si nécessairePlus de lignes de contexte dans les hunks de add -p — nécessite Git 2.51 ou plus récent

Exemple

git add -p -U5 app.js

Expert (6)

Remplacer le bit exécutable des fichiers ajoutés. Utilisez +x pour rendre exécutable, -x pour retirer ce droit.

Si nécessaireActive le bit exécutable dans l’index — utile sous Windows

Exemple

git add --chmod=+x script.sh

Réappliquer le filtre 'clean' à tous les fichiers suivis. Utile après avoir changé les réglages de fins de ligne.

Si nécessaireÀ lancer une fois après avoir changé les règles de fins de ligne de .gitattributes

Exemple

git add --renormalize .

Autoriser la mise à jour d’entrées de l’index hors du cône du sparse checkout. Pour les sparse checkouts avancés seulement.

Si nécessaireSeulement pour les dépôts en sparse checkout qui modifient des chemins hors du cône

Exemple

git add --sparse path/outside/cone

Lire les chemins de fichiers depuis un fichier au lieu de la ligne de commande. Utilisez '-' pour lire depuis stdin.

Si nécessairePour les scripts avec beaucoup de chemins ; évite les limites de longueur de ligne de commande

Exemple

git add --pathspec-from-file=files.txt

Avec -p/-i, afficher le contexte entre les blocs jusqu’au nombre de lignes indiqué, en fusionnant les blocs proches en un seul (0 par défaut, ou diff.interHunkContext). Nécessite Git 2.51 ou plus récent.

Si nécessaireFusionne les hunks proches dans add -p — nécessite Git 2.51 ou plus récent

Exemple

git add -p --inter-hunk-context=5

S’utilise avec --pathspec-from-file. Les éléments du pathspec sont séparés par le caractère NUL au lieu de retours à la ligne. Gère les noms de fichiers avec des caractères spéciaux.

Si nécessaireComplément de --pathspec-from-file pour les noms avec retours à la ligne ou caractères inhabituels

Exemple

git add --pathspec-from-file=files.txt --pathspec-file-nul

Choisir la bonne option

Commandes d’indexation

Quels fichiers sont indexés selon la commande

CommandeNouveaux fichiersFichiers modifiésFichiers supprimésPortée
git add <file>✓✓✓Seulement le fichier indiqué
git add .✓✓✓Dossier courant et en dessous
git add -A✓✓✓Tout le dépôt
git add -u✗✓✓Fichiers suivis seulement
git add --no-all✓✓✗Ignore les suppressions

Options interactives

Des options pour choisir finement ce qui est indexé

CommandeModeGranularitéCas d’usage
git add -pPatchBloc par blocIndexer certaines modifications d’un fichier
git add -eÉditeurLigne par ligneModifier le diff à la main avant d’indexer
git add -iMenuFichier par fichierMenu d’indexation interactif complet

Options d’aperçu et de sortie

Des options qui affichent des informations sans modifier la zone de préparation

CommandeActionModifie l’indexBut
git add -nDry-run✗Prévisualiser ce qui serait préparé
git add -vDétaillé✓Afficher les fichiers au fur et à mesure de l’indexation
git add --refreshRafraîchir✗Mettre à jour seulement les infos stat

Fichiers particuliers

Des options pour les fichiers qui demandent un traitement spécial

CommandeGèreComportementUsage typique
git add -fFichiers ignorésPasser outre .gitignoreAjouter un fichier normalement ignoré
git add -NNouveaux fichiersIntention d’ajout (vide)Suivre un fichier pour git diff sans l’indexer
git add --chmod=+xExécutablesDéfinir le mode du fichierRendre des scripts exécutables
git add --sparseFichiers sparseHors du côneIndexer des fichiers hors du sparse checkout

Options avancées

Des options d’expert pour des cas précis

CommandeButQuand l’utiliser
git add --renormalizeRéappliquer les filtres cleanAprès avoir changé les fins de ligne dans .gitattributes
git add --pathspec-from-fileLire les chemins depuis un fichierIndexer beaucoup de fichiers à partir d’une liste
git add --ignore-errorsContinuer malgré les erreursIndexer ce qui peut l’être, sauter les échecs
git add --no-warn-embedded-repoMasquer l’avertissement de sous-moduleAjouter volontairement des dépôts imbriqués

Exemples de workflows

1
git status

Relire d’abord toutes les modifications

2
git add -A

Indexer tous les fichiers nouveaux, modifiés et supprimés

3
git commit -m "Your message"

Committer toutes les modifications indexées

1
git add -p

Choisir de façon interactive seulement la correction du bug (appuyez sur 'y' pour les blocs du correctif, 'n' pour ceux de la fonctionnalité)

2
git commit -m "Fix login validation bug"

Committer seulement la correction du bug

3
git add -A

Indexer maintenant les modifications restantes de la fonctionnalité

4
git commit -m "Add dark mode toggle"

Committer la fonctionnalité séparément

1
git status

Voir ce qui est modifié et ce qui est non suivi

2
git add -u

Indexer seulement les modifications des fichiers suivis

3
git status

Vérifier que les nouveaux fichiers sont toujours non suivis

4
git commit -m "Update existing files"

Committer sans les nouveaux fichiers

1
git add -n .

Le dry-run montre ce qui serait ajouté

2
git diff

Relire en détail les modifications réelles

3
git add .

Si c’est bon, indexer pour de vrai

1
git add dist/bundle.js

Ceci échoue - le fichier est ignoré

2
git add -f dist/bundle.js

L’ajout forcé passe outre .gitignore

3
git commit -m "Add build for deployment"

Committer le fichier normalement ignoré

Touches du mode interactif

Raccourcis clavier des modes interactifs de git add. Ils fonctionnent en mode patch (-p) et en mode interactif (-i).

Mode patch

-p
yIndexer ce bloc
nNe pas indexer ce bloc
qQuitter ; ne pas indexer ce bloc ni les suivants
aIndexer ce bloc et tous les suivants du fichier
dNe pas indexer ce bloc ni les suivants du fichier
sDécouper le bloc courant en blocs plus petits
eModifier le bloc courant à la main
?Afficher l’aide

Mode interactif

-i
1 / sStatus - afficher l’état actuel de l’indexation
2 / uUpdate - choisir les fichiers à indexer
3 / rRevert - désindexer les fichiers choisis
4 / aAdd untracked - ajouter de nouveaux fichiers
5 / pPatch - entrer en mode patch pour les fichiers choisis
6 / dDiff - afficher le diff des modifications indexées
7 / qQuitter
8 / hAide

Dépannage

Le fichier n’est pas ajouté (ignoré)

Cause : Le fichier correspond à un motif de .gitignore

Cherchez le motif correspondant dans .gitignore. Utilisez -f pour forcer l’ajout si c’est voulu.

git add -f <file>

Erreur « Permission denied »

Cause : Le fichier est verrouillé par un autre processus ou vous n’avez pas le droit de lecture

Fermez les applications qui utilisent le fichier, ou vérifiez ses permissions. Utilisez --ignore-errors pour continuer avec les autres fichiers.

git add --ignore-errors .

Il ne se passe rien avec git add

Cause : Les fichiers sont peut-être déjà indexés, ou il n’y a aucune modification à ajouter

Lancez git status pour voir l’état actuel. Les fichiers déjà indexés ne sont pas ajoutés de nouveau.

git status

Les nouveaux fichiers n’apparaissent pas dans git diff

Cause : Les fichiers non suivis n’apparaissent pas dans git diff par défaut

Utilisez git add -N pour marquer l’intention d’ajout ; git diff montrera alors le contenu.

git add -N <file> && git diff

Avertissement sur un dépôt git imbriqué

Cause : Vous ajoutez un dossier qui contient son propre répertoire .git (un dépôt imbriqué)

Supprimez le dossier .git imbriqué, utilisez les sous-modules git, ou masquez l’avertissement.

git add --no-warn-embedded-repo <folder>

Les fins de ligne apparaissent sans cesse comme des modifications

Cause : Des fins de ligne incohérentes (CRLF ou LF) entre votre système et le dépôt

Configurez .gitattributes avec 'text=auto' et renormalisez tous les fichiers.

git add --renormalize .

Des scripts (par ex. git diff-files) signalent des fichiers modifiés alors que le contenu n’a pas changé

Cause : Les horodatages des fichiers ont changé, donc les infos stat en cache dans l’index sont périmées

Rafraîchissez l’index pour mettre à jour les infos stat sans rien indexer. (git status rafraîchit automatiquement.)

git add --refresh .

Astuces et pièges

Bonnes pratiques

  • ✓Relisez les modifications avant de les indexer : utilisez 'git diff' pour voir ce que vous allez indexer, ou 'git add -p' pour relire de façon interactive.
  • ✓Indexez ensemble les modifications liées : regroupez les modifications logiquement liées dans un seul commit. Ne mélangez pas corrections de bugs et nouvelles fonctionnalités.
  • ✓Utilisez 'git add -p' pour les grosses modifications : quand vous avez fait plusieurs modifications sans rapport dans un fichier, le mode patch permet de les indexer séparément.
  • ✓Consultez souvent git status : lancez toujours 'git status' avant et après l’indexation pour vérifier ce qui sera committé.
  • ✓Méfiez-vous de 'git add .' : cela indexe tout le dossier courant. Pensez à nommer les fichiers précisément ou à utiliser 'git add -p' pour plus de contrôle.
  • ✓Configurez .gitignore d’abord : avant votre premier 'git add', vérifiez que .gitignore exclut les artefacts de build, les dépendances et les fichiers sensibles.
  • ✓Utilisez le dry-run pour vérifier : en cas de doute, 'git add -n .' affiche ce qui serait indexé sans rien indexer.
  • ✓Indexez explicitement les suppressions : supprimer un fichier en local n’indexe pas la suppression. Utilisez 'git add -u' ou 'git add -A' pour inclure les suppressions.

Erreurs fréquentes

  • ✗'git add .' ou 'git add -A' : les deux indexent les fichiers nouveaux, modifiés et supprimés, mais '.' ne couvre que le dossier courant et ses sous-dossiers, alors que '-A' couvre tout l’arbre de travail.
  • ✗Oublier que 'git add' ne committe pas. Les fichiers sont seulement indexés et il faut 'git commit' pour les enregistrer.
  • ✗Ajouter des fichiers qui devraient être ignorés. Vérifiez toujours votre .gitignore avant 'git add -A' ou 'git add .'
  • ✗Ne pas relire les modifications avant de les indexer. Utilisez 'git add -p' pour relire plus attentivement ce que vous indexez.
  • ✗Confondre 'git add -u' et 'git add -A' : '-u' n’indexe que les modifications et suppressions de fichiers suivis, pas les nouveaux fichiers non suivis.

FAQ

A:

Depuis Git 2.0, les deux indexent les fichiers nouveaux, modifiés et supprimés. La différence est la portée : 'git add .' ne couvre que le dossier courant et ses sous-dossiers, alors que 'git add -A' couvre tout le dépôt, quel que soit votre dossier courant.

A:

Le fichier est probablement listé dans .gitignore. Vérifiez avec 'git check-ignore <file>'. Si vous devez quand même l’ajouter, forcez avec 'git add -f <file>'.

A:

Oui ! Utilisez 'git restore --staged <file>' (ou 'git reset HEAD <file>' dans les anciennes versions de Git) pour désindexer un fichier sans perdre vos modifications.

A:

Utilisez 'git add -p <file>' pour entrer dans le mode patch interactif. Git vous montre chaque modification (hunk) et vous laisse choisir lesquelles indexer avec y/n.

A:

Cela vient en général de changements de fins de ligne (CRLF/LF) ou de permissions. Regardez 'git diff' pour voir ce qui a changé. Configurez .gitattributes pour gérer les fins de ligne.

A:

Ajoutez d’abord les fichiers à exclure dans .gitignore, puis utilisez 'git add .'. Sinon, ajoutez les fichiers un par un ou utilisez des motifs comme 'git add *.js'.

A:

Il indique à Git que vous comptez ajouter le fichier plus tard. Le fichier devient suivi (il apparaît dans git diff) mais son contenu n’est pas encore indexé. Pratique pour relire de nouveaux fichiers avant de committer.

A:

Non, Git ne suit que des fichiers, pas des dossiers. L’astuce habituelle est d’ajouter un fichier .gitkeep ou .gitignore dans le dossier vide.