git restore

O que o git restore faz

O comando git restore copia uma versão limpa de um arquivo para a sua árvore de trabalho, para a área de stage, ou para ambas. Introduzido no Git 2.23 junto com o git switch, ele assumiu as responsabilidades de nível de arquivo que antes estavam enterradas dentro do sobrecarregado comando git checkout. Sua função é responder a uma pergunta: de onde deve vir a cópia boa deste arquivo, e onde ela deve terminar?

Para usá-lo bem, é útil conhecer as "três árvores" do Git: a árvore de trabalho (os arquivos que você edita no disco), o índice (também chamado de área de stage — onde o git add escreve e o que o próximo commit vai capturar), e o HEAD (o snapshot do seu último commit). O git restore sempre move conteúdo de uma origem para um destino entre esses locais. Dois sinalizadores controlam isso:

• --source=<rev> — de onde vem a cópia limpa. Por padrão, é o índice, ou o HEAD quando --staged é usado.
• --staged e/ou --worktree — onde a cópia é escrita. Por padrão, é --worktree.

Esta página cobre os usos do dia a dia: descartar edições, remover do stage, restaurar a partir de um commit mais antigo, recuperar um arquivo excluído, e como o restore difere do reset e do revert.

Descartando alterações na árvore de trabalho

Por padrão, o git restore sobrescreve um arquivo no seu diretório de trabalho com a versão da área de stage (o índice). Se você editou um arquivo e quer descartar essas edições:

git restore index.html

O arquivo retorna ao seu último estado staged (ou ao estado do HEAD se nunca foi colocado em stage). Como isso é destrutivo — suas edições não staged são perdidas definitivamente e não podem ser recuperadas com git reflog — o Git deliberadamente dá à operação um nome claro e explícito em vez de escondê-la por trás do checkout.

Para descartar alterações em vários arquivos de uma vez, passe um diretório ou um pathspec. Este é um dos poucos comandos git restore que pode apagar muito trabalho com um único pressionamento de tecla, então verifique o que está sem commit primeiro com git status:

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

Removendo do stage com --staged

Para remover um arquivo da área de stage sem alterar seu conteúdo no disco, use --staged. Isso copia a versão do HEAD de volta para o índice, deixando as edições da sua árvore de trabalho intactas:

git restore --staged index.html

Este é o substituto moderno do git reset HEAD <file>, e é exatamente o que o Git sugere no texto de dica quando você executa git status após colocar algo em stage:

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

Restaurando a partir de um commit específico

A opção --source permite que você obtenha o conteúdo de um arquivo de qualquer commit, branch ou tag — não apenas do índice ou do HEAD:

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

Isso retorna um único arquivo ao estado que ele tinha dois commits atrás. Note o que ele não faz: não cria um commit e não move nenhum ponteiro de branch. O conteúdo antigo vai para a sua árvore de trabalho como uma alteração não staged comum, pronta para você inspecionar, colocar em stage e fazer commit. Você pode usar um nome de branch (--source=main) ou uma tag (--source=v1.0) com a mesma facilidade.

Recuperando um arquivo excluído

Se você excluiu um arquivo rastreado por engano e não fez commit da exclusão, o git restore o traz de volta do índice ou do HEAD:

git restore app.js

Como o arquivo ainda existe em um snapshot conhecido e íntegro, o Git o reescreve no disco exatamente como estava. (Se você já fez commit da exclusão, restaure-o de antes daquele commit: git restore --source=HEAD~1 app.js.)

Resetando ambas as cópias de uma vez

Combinar --staged e --worktree reseta um arquivo completamente — tanto a cópia staged quanto a cópia em disco — de volta ao HEAD:

git restore --staged --worktree index.html

Este é o comando "faça este arquivo parecer exatamente com o último commit, independentemente do que eu fiz". Ele descarta edições staged e não staged em um único passo.

Restaurando parte de um arquivo

Assim como git add e git checkout, o git restore suporta um modo de patch. Com -p (ou --patch), o Git percorre cada hunk de alteração e pergunta se deve descartá-lo, para que você possa descartar algumas edições enquanto mantém outras:

git restore -p index.html

Isso é útil quando você fez várias alterações não relacionadas em um arquivo e quer desfazer apenas um experimento específico.

Opções comuns

restore vs reset vs revert

Esses três comandos são fáceis de confundir porque todos eles "desfazem" algo, mas funcionam em níveis diferentes:

• git restore opera em arquivos na árvore de trabalho e no índice. Nunca move ponteiros de branch nem reescreve o histórico.
• git reset move a ponta do branch atual e pode alterar a área de stage — opera no nível de commit.
• git revert cria um novo commit que desfaz um anterior, deixando o histórico existente intacto.

Use restore quando simplesmente quiser que um arquivo pareça com como estava em algum outro lugar. Se você quiser remover commits inteiros ou mover um branch, esse é o trabalho do git reset. Se as alterações já foram publicadas e compartilhadas, use git revert para não reescrever o histórico do qual outros dependem. Para reservar alterações temporariamente em vez de descartá-las, consulte git stash.

Prática