Si vous avez indexé un fichier dans un projet Git sur votre Mac mais souhaitez l'exclure du prochain commit, exécutez git restore --staged pour ce fichier depuis le Terminal. Cela met à jour la zone de staging de Git tout en conservant le fichier dans votre répertoire de travail, afin que ses modifications restent disponibles pour être examinées ou indexées plus tard. Vérifiez le chemin du fichier et confirmez le résultat avec git status avant de commiter.

Ce que modifie le fait de « désindexer »

Git conserve la proposition du prochain commit dans son index, également appelé la zone de staging (ou d'indexation). Un commit comprend normalement les modifications indexées ; les modifications que vous n'avez pas indexées restent dans votre arbre de travail. Retirer un fichier de l'index modifie donc ce qui est préparé pour le commit, sans demander à Git de réécrire la copie de travail. La documentation de Git indique que git restore --staged restaure par défaut l'index depuis HEAD. Documentation de restore par Git

Cela s'avère utile lorsque vous avez indexé le mauvais fichier ou avez décidé qu'un fichier particulier ne devait pas faire partie d'un commit. La commande s'applique spécifiquement au fichier lorsque vous lui fournissez un seul chemin. N'ajoutez pas --worktree : la documentation de Git précise que l'utilisation conjointe de --staged et --worktree restaure les deux emplacements, ce qui n'est pas le but recherché lorsque vous souhaitez conserver vos modifications.

Désindexer un fichier depuis le Terminal

Ouvrez le Terminal sur votre Mac et placez-vous dans le dossier du dépôt. Le shell par défaut de Terminal est zsh, bien qu'un Mac géré en entreprise puisse utiliser un shell différent. Guide de Terminal par Apple

Exécutez d'abord git status. Repérez le fichier indexé sous « Changes to be committed » (Modifications qui seront validées) et notez son chemin relatif par rapport à la racine du dépôt. Si vous voyez un dépôt différent ou si le chemin n'est pas clair, arrêtez-vous et vérifiez votre emplacement avant de modifier quoi que ce soit.

Par exemple, pour désindexer src/Feature.swift, exécutez :

git restore --staged -- src/Feature.swift

Le -- sépare les options du chemin. Il est utile pour les noms qui pourraient autrement être interprétés comme des options. Mettez les chemins contenant des espaces entre guillemets afin que zsh transmette le chemin comme un seul argument :

git restore --staged -- "Documentation/Setup Notes.md"

Utilisez le chemin tel que Git l'indique, en respectant les majuscules et les éventuels noms de répertoires. Si vous vous trouvez déjà dans un sous-répertoire du dépôt, la gestion des chemins par Git peut être moins évidente ; exécuter la commande depuis la racine du dépôt et utiliser le chemin complet relatif au dépôt permet de vérifier la cible plus facilement.

Confirmer que les modifications sont toujours présentes

Exécutez à nouveau git status. Pour un fichier suivi et modifié, la modification indexée doit disparaître de « Changes to be committed » et apparaître sous « Changes not staged for commit » (Modifications qui ne seront pas validées). Cela signifie que la copie de travail diffère toujours de HEAD, mais que l'index ne contient plus cette proposition de modification. Git décrit le statut comme montrant les différences entre HEAD et l'index, ainsi qu'entre l'index et l'arbre de travail. Documentation de add par Git

Vous pouvez inspecter les modifications non indexées avec :

git diff -- "src/Feature.swift"

Ce diff compare le fichier de travail avec l'index. Comme l'index correspond désormais à HEAD pour ce fichier suivi, il affiche les modifications conservées que vous avez retirées de l'index. Pour préparer le fichier pour un commit ultérieur, indexez-le de nouveau avec git add -- "src/Feature.swift".

À quoi s'attendre pour les nouveaux fichiers et les suppressions

Si le fichier est nouveau et n'a jamais été commité, il n'a aucune version dans HEAD. Une fois que git restore --staged -- path/to/new-file l'a retiré de l'index, le fichier doit rester sur le disque en tant que fichier non suivi (untracked). Vérifiez qu'il apparaît sous « Untracked files » (Fichiers non suivis) dans git status ; ne le supprimez pas si vous souhaitez le conserver.

Si vous avez indexé la suppression d'un fichier suivi, restaurer l'index depuis HEAD replace la version suivie dans l'index, tandis que la copie de travail reste supprimée. L'état (status) devrait indiquer une suppression non indexée. Cette distinction est importante : désindexer ne fait pas nécessairement apparaître l'arbre de travail comme inchangé ; cela préserve l'état actuellement présent sur le disque.

Si vous n'avez indexé qu'une partie du fichier

La même commande désindexe la totalité du contenu indexé du fichier. Si vous avez délibérément indexé certains sections (hunks) et ne souhaitez garder que certaines d'entre elles indexées, n'exécutez pas la commande s'appliquant au fichier entier. La commande restore de Git prend en charge un mode patch interactif, mais sélectionner la bonne direction et les bonnes sections demande de la prudence. Consultez le comportement documenté de git restore --patch par Git avant de l'utiliser ; Git documente également git add --patch pour choisir interactivement les sections à indexer. Documentation de restore par Git

Évitez git restore --worktree ou git restore --staged --worktree pour cette tâche. Ces options affectent l'arbre de travail et peuvent effacer les modifications exactes que vous essayez de conserver. Si le résultat dans git status diffère de ce que vous attendiez, faites une pause et examinez le chemin et le diff avant d'exécuter une autre commande restore.

Sources