git restore

Ce que fait git restore

La commande git restore copie une version propre d'un fichier dans votre répertoire de travail, votre zone de transit, ou les deux. Introduite dans Git 2.23 avec git switch, elle a repris les responsabilités au niveau des fichiers qui étaient auparavant enfouies dans la commande surchargée git checkout. Son rôle est de répondre à une question : d'où doit provenir la bonne version de ce fichier, et où doit-elle atterrir ?

Pour bien l'utiliser, il est utile de connaître les « trois arbres » de Git : le répertoire de travail (les fichiers que vous modifiez sur le disque), l'index (également appelé zone de transit — ce que git add écrit et ce que le prochain commit capturera), et HEAD (l'instantané de votre dernier commit). git restore déplace toujours du contenu depuis une source vers une destination parmi ces éléments. Deux options contrôlent cela :

• --source=<rev> — d'où provient la copie propre. Par défaut, depuis l'index, ou depuis HEAD quand --staged est utilisé.
• --staged et/ou --worktree — où la copie est écrite. Par défaut, --worktree.

Cette page couvre les usages quotidiens : annuler des modifications, désindexer, restaurer depuis un ancien commit, récupérer un fichier supprimé, et les différences entre restore, reset et revert.

Annuler des modifications dans le répertoire de travail

Par défaut, git restore écrase un fichier dans votre répertoire de travail avec la version provenant de la zone de transit (l'index). Si vous avez modifié un fichier et souhaitez annuler ces modifications :

git restore index.html

Le fichier revient à son dernier état indexé (ou à son état HEAD s'il n'a jamais été indexé). Comme cette opération est destructrice — vos modifications non indexées sont définitivement perdues et ne peuvent pas être récupérées avec git reflog — Git donne délibérément à l'opération un nom clair et explicite plutôt que de la cacher derrière checkout.

Pour annuler les modifications sur plusieurs fichiers à la fois, passez un répertoire ou un pathspec. C'est l'une des rares commandes git restore qui peut effacer beaucoup de travail en une seule frappe, alors vérifiez d'abord ce qui n'est pas commité avec git status :

git restore .          # discard all changes in the current directory
git restore src/       # discard all changes under src/

Désindexer avec --staged

Pour retirer un fichier de la zone de transit sans modifier son contenu sur le disque, utilisez --staged. Cela copie la version de HEAD dans l'index, laissant vos modifications du répertoire de travail intactes :

git restore --staged index.html

C'est le remplaçant moderne de git reset HEAD <file>, et c'est exactement ce que Git suggère dans son texte d'aide quand vous exécutez git status après avoir indexé quelque chose :

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   index.html

Restaurer depuis un commit spécifique

L'option --source vous permet de récupérer le contenu d'un fichier depuis n'importe quel commit, branche ou tag — pas seulement l'index ou HEAD :

git restore --source=HEAD~2 config.yml

Cela remet un seul fichier dans l'état où il était deux commits auparavant. Notez ce que cela ne fait pas : cela ne crée pas de commit et ne déplace aucun pointeur de branche. L'ancien contenu atterrit dans votre répertoire de travail comme une modification ordinaire non indexée, prête à être inspectée, indexée et commitée. Vous pouvez utiliser un nom de branche (--source=main) ou un tag (--source=v1.0) tout aussi facilement.

Récupérer un fichier supprimé

Si vous supprimez par erreur un fichier suivi et n'avez pas commité la suppression, git restore le ramène depuis l'index ou HEAD :

git restore app.js

Comme le fichier existe encore dans un instantané valide, Git le réécrit sur le disque exactement tel qu'il était. (Si vous avez déjà commité la suppression, restaurez-le depuis avant ce commit : git restore --source=HEAD~1 app.js.)

Réinitialiser les deux copies à la fois

Combiner --staged et --worktree réinitialise complètement un fichier — à la fois la copie indexée et la copie sur le disque — vers HEAD :

git restore --staged --worktree index.html

C'est la commande « fais en sorte que ce fichier ressemble exactement au dernier commit, quoi que j'aie fait ». Elle annule les modifications indexées et non indexées en une seule étape.

Restaurer une partie d'un fichier

Comme git add et git checkout, git restore supporte un mode interactif. Avec -p (ou --patch), Git vous guide à travers chaque bloc de modification et vous demande si vous souhaitez l'annuler, vous pouvez ainsi supprimer certaines modifications tout en conservant d'autres :

git restore -p index.html

C'est utile lorsque vous avez effectué plusieurs modifications sans rapport dans un fichier et ne souhaitez annuler qu'une expérience spécifique.

Options courantes

restore vs reset vs revert

Ces trois commandes sont faciles à confondre car elles « annulent » toutes quelque chose, mais elles fonctionnent à des niveaux différents :

• git restore opère sur des fichiers dans le répertoire de travail et l'index. Il ne déplace jamais les pointeurs de branche ni ne réécrit l'historique.
• git reset déplace l'extrémité de la branche courante et peut modifier la zone de transit — il opère au niveau des commits.
• git revert crée un nouveau commit qui annule un commit précédent, laissant l'historique existant intact.

Utilisez restore quand vous souhaitez simplement qu'un fichier ressemble à ce qu'il était à un autre endroit. Si vous souhaitez supprimer des commits entiers ou déplacer une branche, c'est le rôle de git reset. Si les modifications sont déjà poussées et partagées, utilisez git revert pour ne pas réécrire l'historique dont d'autres dépendent. Pour mettre de côté des modifications temporairement au lieu de les annuler, consultez git stash.

Pratique