Почему файл игнорируется? Отладка с git check-ignore

Когда правил становится много, возникают вопросы: «Почему я не вижу этот файл?» или «Почему он всё ещё виден?» В git есть команда, которая на них отвечает.

git check-ignore -v

git check-ignore -v logs/app.log src/build/keep.txt

Вывод имеет формат источник:номер_строки:шаблон<Tab>путь.

.gitignore:3:*.log	logs/app.log

• Источник — файл, в котором находится правило. Выводится .gitignore, sub/.gitignore, .git/info/exclude или путь к глобальному файлу.
• По номеру строки и шаблону видно, какая именно это строка.
• Если ничего не выводится, путь не игнорируется.
• С -v при возврате через ! тоже показывается отрицающее правило, например .gitignore:4:!keep.log keep.log.
• Для файла в исключённом родительском каталоге показывается правило этого каталога. Например, если причина в правиле logs/, выводится .gitignore:1:logs/ logs/keep.txt.

Чтобы видеть и несовпавшие пути, добавьте --non-matching (-n).

Отслеживаемые файлы: --no-index

К уже отслеживаемым файлам правила игнорирования не применяются, поэтому check-ignore по умолчанию тоже ничего не выводит. Если нужно лишь узнать, совпадает ли правило с файлом, добавьте --no-index.

$ git check-ignore -v app.log            # отслеживается, поэтому вывода нет
$ git check-ignore -v --no-index app.log
.gitignore:3:*.log	app.log

Просмотр списка игнорируемых файлов

# Показать игнорируемые элементы вместе со статусом (отметка !!)
git status --ignored --short

# Перечислить все игнорируемые файлы по одному
git ls-files --others --ignored --exclude-standard

# Отслеживаемые файлы, попадающие под правила игнорирования
git ls-files -ci --exclude-standard

Если каталог игнорируется целиком, git status --ignored показывает его одной строкой, например !! logs/. Чтобы видеть отдельные файлы, используйте ls-files.

Частые причины, по которым правило не срабатывает

1. Файл уже отслеживается. Самая частая причина. Если git ls-files <путь> что-то выводит, файл отслеживается. Снимите отслеживание через git rm --cached.
2. Исключён родительский каталог. Если игнорируется dir/, правило !dir/file не действует. Замените на dir/*.
3. Перепутан порядок. Если после отрицающего правила снова идёт более широкое, побеждает оно. Номер строки в check-ignore -v сразу это покажет.
4. Конечные пробелы. Пробел в конце *.log удаляется, а вот пробелы перед шаблоном и невидимые символы вроде полноширинного пробела остаются частью шаблона.
5. Направление слеша. gitignore даже в Windows использует разделителем пути только /. В build\output обратный слеш трактуется как экранирование, и правило работает не так, как задумано.
6. Ошибка с привязкой. config/local.json из-за слеша в середине совпадает только с config в корне. Для любой глубины используйте **/config/local.json.
7. Регистр букв. В окружениях, где core.ignorecase равно false (обычно Linux), *.JPG и *.jpg различаются. Репозитории, созданные в macOS или Windows, обычно имеют true, поэтому правило может работать локально и не работать в CI.

Предварительная проверка в браузере

Если хочется менять правила и сравнивать результат до применения в репозитории, удобна вкладка Тест шаблонов на этом сайте. Вставьте правила и список путей — для каждого пути будут показаны результат, решающее правило (с номером строки) и случаи, когда путь игнорируется из-за родительского каталога. В качестве списка путей можно прямо использовать вывод git ls-files или find . -type f. Однако окончательный результат с учётом .gitignore в подкаталогах и глобальной настройки проверяйте в репозитории через git check-ignore -v.

Источники

• Официальная документация git-check-ignore
• Официальная документация git-status: --ignored
• Официальная документация git-ls-files
• Дата проверки: 2026-09-23 (формат вывода проверен в git 2.50.1)