git clean: удалить неотслеживаемые файлы

git clean стирает из рабочего каталога файлы, о которых git ничего не знает: собранные артефакты, временные файлы, распакованный куда попало архив.

Разница с git restore тут принципиальная. Restore возвращает изменённые файлы к тому виду, который лежит в истории: у git есть чем их заменить. Clean работает с файлами, которых в истории не было ни разу, и заменять их нечем. Он просто удаляет их с диска.

Поэтому порядок всегда из двух шагов. Сначала смотришь список:

$ git clean -n
Would remove archive.zip
Would remove notes-copy.txt

-n (то же самое, что --dry-run) ничего не делает, а только печатает, что уехало бы. Прочитал список, согласился - повторяешь с -f:

$ git clean -f
Removing archive.zip
Removing notes-copy.txt

Флаг -f обязателен. Без него git отказывается работать:

$ git clean
fatal: clean.requireForce is true and -f not given: refusing to clean

Это намеренная защита от случайного нажатия Enter.

Флаги, которые расширяют охват

По умолчанию команда трогает только файлы. Каталоги забирает -d:

$ git clean -nd
Would remove archive.zip
Would remove build/
Would remove notes-copy.txt

Всё, что спрятано через .gitignore, clean по умолчанию обходит стороной. Флаг -x снимает это исключение:

$ git clean -ndx
Would remove .env
Would remove archive.zip
Would remove build/
Would remove node_modules/
Would remove notes-copy.txt

Вот здесь стоит притормозить. В список попали .env с локальными паролями и node_modules со всеми зависимостями - ровно то, что лежит в .gitignore и обычно нужно для работы. git clean -fdx приводит каталог проекта к состоянию свежего клона; иногда это именно то, что требуется перед сборкой с нуля, но .env после такой уборки придётся собирать заново руками.

Решать по каждому файлу отдельно позволяет интерактивный режим -i:

$ git clean -i
Would remove the following items:
  junk1.txt  junk2.txt
*** Commands ***
    1: clean                2: filter by pattern    3: select by numbers
    4: ask each             5: quit                 6: help
What now>

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

Главное: удалённое через git clean не возвращается. Ни git reflog, ни git restore тут не помогут. Этих файлов никогда не было ни в коммите, ни в индексе, и в каталоге .git не осталось ни одной их копии. Git отменяет почти всё, но это одна из немногих необратимых команд, наравне с git reset --hard.

Вторая ошибка - забыть, где стоишь. Команда работает от текущего каталога и вниз, так что git clean -fdx в корне репозитория сносит куда больше, чем та же команда в подкаталоге. Привычка сначала запускать -n и читать список закрывает обе ошибки разом.

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

Чем clean отличается от restore и почему .gitignore его останавливает, разобрано здесь: Глава 4. Посмотреть, отменить, спрятать лишнее.