git restore: вернуть файл и вынуть его из индекса

git restore отменяет сделанное на уровне файла: с флагом --staged убирает файл из индекса, без флага возвращает его к виду из последнего коммита. Отмена в git разложена по уровням, и эта команда закрывает два нижних.

Первый уровень: файл уже лежит в индексе (staging area), а коммитить его ты передумал.

$ git status --short
M  report.txt

$ git restore --staged report.txt
$ git status --short
 M report.txt

Два столбца в коротком выводе git status читаются так: первый - индекс, второй - рабочий каталог. M значит «изменение отобрано в индекс», M - «изменение есть только в файле». Команда переносит букву из первого столбца во второй и ничего не теряет: git add вернёт всё как было.

Второй уровень: правки в самом файле оказались мусором и файл надо вернуть к последнему коммиту.

$ git restore report.txt
$ git status
On branch main
nothing to commit, working tree clean

Тут стоит притормозить. Файл затёрт содержимым из архива, а правки, которых git ни разу не видел, пропали навсегда: восстанавливать ему нечего. Перед такой командой полезно глянуть git diff.

Источник по умолчанию - индекс, а когда в индексе ничего не отложено, там лежит содержимое последнего коммита. Взять версию из другого коммита можно флагом --source:

$ git restore --source=HEAD~1 report.txt   # версия из предпоследнего коммита
$ git restore .                            # откатить все файлы в текущем каталоге

Случайно стёртый файл возвращается той же командой: после rm report.txt выполни git restore report.txt, и файл снова окажется на диске.

Частые ошибки

--staged часто принимают за полную отмену. Флаг трогает только индекс, содержимое файла на диске остаётся прежним. Чтобы вычистить обе зоны сразу, нужны оба флага: git restore --staged --worktree report.txt.

Вторая ловушка - советы из статей, написанных до 2019 года: там для тех же задач предлагают git checkout -- file и git reset HEAD file. Команды рабочие и никуда не делись, но у каждой из них несколько несвязанных ролей. В версии 2.23 роли развели: git switch переключает ветки, git restore восстанавливает файлы, git reset двигает указатель ветки.

Где это в учебнике

Отмена по уровням разобрана в четвёртой главе, там же про git diff и .gitignore.

Глава 4. Посмотреть, отменить, спрятать лишнее

Потренироваться руками - в интерактивном уроке Отмена изменений.