git clean

Что делает git clean

Команда git clean удаляет неотслеживаемые файлы из рабочего каталога. Неотслеживаемый файл — это файл, который существует на диске, но Git ещё не следит за ним: он ни разу не был добавлен через git add и не находится в индексе.

Это отличает git clean от соседних команд отмены изменений:

• git reset перемещает указатель ветки и может убрать из индекса отслеживаемые изменения.
• git checkout восстанавливает отслеживаемые файлы до предыдущего состояния.
• git clean удаляет файлы, которые Git вообще не отслеживает.

Вместе они покрывают всё рабочее дерево: reset/checkout работают с отслеживаемым и проиндексированным содержимым, clean — с остальным. Типичный сценарий — удалить артефакты сборки, сгенерированные файлы или остатки экспериментов, чтобы начать с чистой копии зафиксированного дерева.

git clean необратима. Она удаляет файлы напрямую из файловой системы, а не в восстанавливаемую область вроде stash. Отмены git clean не существует. Всегда выполняйте предварительный просмотр с помощью пробного запуска (-n).

Пример ниже создаёт репозиторий с одним отслеживаемым и несколькими неотслеживаемыми элементами, чтобы вы могли увидеть разницу:

Создание тестового репозитория

mkdir test_directory
cd test_directory/
git init .
#Initialized empty Git repository in /Users/kev/code/test_directory/.git/
echo "tracked file" > ./test_tracked_file
git add ./test_tracked_file
echo "untracked" > ./test_untracked_file
mkdir ./test_untracked_dir && touch ./test_untracked_dir/file
git status
#On branch master
#No commits yet
#Changes to be committed:
#  (use "git rm --cached <file>..." to unstage)
#        new file:   test_tracked_file
#Untracked files:
#  (use "git add <file>..." to include in what will be committed)
#        test_untracked_dir/
#        test_untracked_file

После выполнения этих команд у вас будет свежий репозиторий с одним проиндексированным файлом test_tracked_file, неотслеживаемым файлом (test_untracked_file) и неотслеживаемым каталогом (test_untracked_dir). git status выводит их в отдельных секциях — именно это разграничение важно для git clean. Все последующие примеры работают с этим репозиторием.

Почему требуется force

Если запустить команду без аргументов, Git откажет:

git clean
#fatal: clean.requireForce defaults to true and neither -i, -n, nor -f given; refusing to clean

Поскольку удаление необратимо, Git не выполнит команду, пока вы явно не укажете -f (force), -n (пробный запуск) или -i (интерактивный режим). Значение по умолчанию можно изменить через параметр git config clean.requireForce, но оставить его включённым — безопаснее.

Основные параметры и использование

Поведение git clean почти полностью определяется несколькими короткими флагами, которые можно свободно комбинировать.

-n: пробный запуск (предпросмотр)

Флаг -n (или --dry-run) выводит список того, что будет удалено, не удаляя ничего фактически. Сделайте этот шаг первым по умолчанию.

git clean -n
#Would remove test_untracked_file

В выводе упоминается test_untracked_file. Обратите внимание: неотслеживаемый каталог не указан, потому что по умолчанию git clean игнорирует каталоги (см. флаг -d ниже).

-f: принудительное удаление

Флаг -f (или --force) выполняет фактическое удаление. Он обязателен, если только clean.requireForce не установлен в false.

git clean -f
#Removing test_untracked_file

test_untracked_file теперь удалён; последующий git status больше его не показывает. По умолчанию git clean -f действует на все неотслеживаемые файлы в текущем каталоге. Файлы, соответствующие правилам .gitignore, остаются нетронутыми, если не добавить -x (см. ниже).

Чтобы ограничить операцию конкретным местом, укажите путь:

git clean -f path/to/dir

-d: включить неотслеживаемые каталоги

По умолчанию git clean пропускает неотслеживаемые каталоги. Добавьте -d, чтобы удалять и их. Сначала используйте -n для предпросмотра, затем -f для выполнения:

git clean -dn
#Would remove test_untracked_dir/
#Would remove test_untracked_file
git clean -df
#Removing test_untracked_dir/
#Removing test_untracked_file

С флагом -d пробный запуск теперь выводит и каталог, и неотслеживаемый файл, а принудительный запуск удаляет оба — каталог вместе со всем его содержимым.

-x: включить игнорируемые файлы

По умолчанию git clean учитывает .gitignore. Флаг -x указывает удалять также игнорируемые файлы — например, node_modules/, результаты сборки или каталоги редакторов вроде .idea/. Это мощный инструмент, о котором легко пожалеть, поэтому всегда сначала выполняйте пробный запуск.

git clean -xn
#Would remove .idea/
#Would remove build/

-x сочетается с другими флагами. Комбинация ниже за один раз удаляет неотслеживаемые файлы, неотслеживаемые каталоги и игнорируемые файлы — это эквивалентно «сбросить рабочую копию до точного состояния зафиксированного дерева»:

git clean -xdf

Краткий справочник

Интерактивный режим

Если вы не уверены, что именно следует удалить, запустите git clean в интерактивном режиме с флагом -i. Это наиболее безопасный способ очистить загрязнённое рабочее дерево, поскольку ничего не удаляется до вашего подтверждения. В примере ниже также добавлен флаг -d, чтобы включить каталоги. Git выводит список кандидатов и приглашение What now> с шестью командами:

git clean -di
#Would remove the following items:
#  test_untracked_dir/ test_untracked_file
#*** Commands ***
#    1: clean                2: filter by pattern    3: select by numbers
#    4: ask each             5: quit                 6: help
#What now>

Вот что делает каждая команда.

6 — help. Введите 6, чтобы вывести описание всех команд:

What now> 6
#clean               - start cleaning files and directories
#filter by pattern   - exclude items from deletion
#select by numbers   - select items to be deleted by numbers
#ask each            - confirm each deletion (like "rm -i")
#quit                - stop cleaning
#help                - this screen
#?                   - help for prompt selection

1 — clean. Удаляет текущие элементы из списка и выходит:

What now> 1
#Removing test_untracked_dir/
#Removing test_untracked_file

2 — filter by pattern. Позволяет исключить элементы по шаблону glob. Здесь шаблон *_file убирает test_untracked_file из списка удаления, оставив в очереди только каталог:

What now> 2
#test_untracked_dir/ test_untracked_file
#Input ignore patterns>> *_file
#test_untracked_dir/

3 — select by numbers. Уточняет список по номеру элемента, а не по шаблону. Git нумерует каждого кандидата, и вы вводите номера тех, что нужно оставить:

What now> 3
#           1: test_untracked_dir/  2: test_untracked_file
#Select items to delete>>

4 — ask each. Проходит по каждому кандидату с приглашением y/N, как rm -i. Ответьте N, чтобы сохранить элемент:

What now> 4
#Remove test_untracked_dir/ [y/N]? N
#Remove test_untracked_file [y/N]? N

5 — quit. Выходит из интерактивного режима без удаления чего-либо:

What now> 5
#Bye.

git clean в сравнении со stash и reset

git clean затрагивает только неотслеживаемые файлы, поэтому используйте её, когда хотите выбросить работу, а не сохранить. Если изменения могут понадобиться позже, воспользуйтесь одной из этих альтернатив:

• git stash — откладывает отслеживаемые изменения (а с флагом -u — и неотслеживаемые файлы), чтобы впоследствии их восстановить. Обратимо.
• git reset — перемещает указатель ветки и убирает из индекса или отбрасывает отслеживаемые изменения.
• git checkout — восстанавливает отслеживаемые файлы до их зафиксированного состояния.

Распространённый способ полностью сбросить рабочее дерево — комбинировать reset для отслеживаемого содержимого с clean для неотслеживаемого:

git reset --hard   # discard tracked changes
git clean -xdf     # remove untracked and ignored files

После выполнения этих двух команд рабочий каталог будет точно соответствовать последнему коммиту, без каких-либо посторонних файлов.

Практика