.gitignore

Обзор

В рабочей копии Git видит каждый файл в одном из трёх состояний: отслеживаемый (уже в репозитории или проиндексированный), неотслеживаемый (новый и ещё не проиндексированный) или игнорируемый (намеренно исключённый). В этой главе объясняется, как заставить Git игнорировать файлы с помощью .gitignore: синтаксис шаблонов, где могут располагаться правила игнорирования (на уровне каталога, репозитория и глобально), а также как обрабатывать сложные случаи — игнорирование файла, который уже закоммичен, принудительный коммит игнорируемого файла, сохранение игнорируемых файлов в stash и отладка причин игнорирования.

Игнорируемые файлы — это те файлы, которые вы явно указали Git пропускать. Они никогда не индексируются, не коммитятся и не появляются в выводе git status как неотслеживаемые. Типичные кандидаты — файлы, генерируемые из исходного кода, а не создаваемые вручную:

• Файлы, создаваемые во время выполнения, — логи, lock-файлы (*.log, *.lock).
• Метаданные ОС и IDE — .DS_Store, Thumbs.db, .idea/, .vscode/.
• Скомпилированные артефакты и зависимости — *.o, *.class, node_modules/, dist/.
• Секреты и локальная конфигурация — .env, файлы с учётными данными.

Простое правило: если файл можно воссоздать из исходников репозитория или он специфичен для вашей машины — игнорируйте его.

Шаблоны игнорирования Git

Правила игнорирования хранятся в текстовом файле .gitignore. Команды git ignore не существует — файл создаётся и редактируется вручную, а затем коммитится как любой другой файл. Каждая непустая строка является шаблоном, сопоставляемым с путями файлов; файл игнорируется, если соответствует какому-либо шаблону.

К формату файла применяются следующие правила:

• Пустая строка ничему не соответствует и используется только для читаемости.
• Строка, начинающаяся с #, является комментарием. Чтобы сопоставить имя файла, буквально начинающееся с #, экранируйте его как \#.
• Пробелы в конце строки игнорируются, если не экранированы обратным слешем (\).
• Шаблоны сопоставляются относительно каталога, в котором находится файл .gitignore.

Сами шаблоны строятся из следующих символов:

Ниже приведён небольшой пример .gitignore, показывающий поведение debug?.log (символ ? соответствует ровно одному символу). Он игнорирует debug0.log и debug1.log, но не debug10.log, поскольку 10 — это два символа:

шаблоны .gitignore

debug?.log

# matches debug0.log, debug1.log, debug9.log
# does NOT match debug10.log (two characters)

Общие файлы .gitignore в репозитории

В репозитории можно определить несколько файлов .gitignore в разных каталогах. Каждый шаблон проверяется относительно каталога, в котором находится этот файл. Однако простейший способ — определить один .gitignore в корне репозитория.

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

Персональные правила игнорирования Git

Персональные правила игнорирования для отдельного репозитория можно разместить в специальном файле .git/info/exclude. Его синтаксис идентичен .gitignore, но поскольку каталог .git не является частью содержимого репозитория, эти правила не версионируются и не распространяются при push-е или клонировании. Используйте этот файл для резервных копий редактора, черновых файлов или всего, что специфично для вашего рабочего процесса и не должно затрагивать остальных участников команды.

Глобальные правила игнорирования Git

Вы можете задать свойство Git core.excludesFile, чтобы указать глобальные шаблоны игнорирования для всех репозиториев на вашем локальном компьютере. Этот файл создаётся вами самостоятельно. Удобнее всего разместить глобальный .gitignore в домашнем каталоге. После создания файла настройте его расположение с помощью команды git config следующим образом:

глобальные правила gitignore

touch ~/.gitignore
git config --global core.excludesFile ~/.gitignore

Игнорирование ранее закоммиченного файла

Добавление шаблона в .gitignore не останавливает отслеживание файла, который уже был закоммичен, — правила игнорирования применяются только к неотслеживаемым файлам. Чтобы начать игнорировать такой файл, необходимо сначала удалить его из индекса Git. Используйте git rm с параметром --cached: это проиндексирует удаление файла из репозитория, сохранив копию на диске как игнорируемый файл. Затем закоммитьте изменение.

игнорирование закоммиченных файлов в .gitignore

echo debug.log >> .gitignore
git rm --cached debug.log
#rm 'debug.log'
git commit -m "Start ignoring debug.log"

Если вы также хотите удалить файл из рабочего каталога, уберите --cached (git rm debug.log). Используйте git status после этого, чтобы убедиться, что файл больше не отображается как отслеживаемый или неотслеживаемый.

Коммит игнорируемого файла

Игнорируемый файл можно добавить в репозиторий с помощью параметра -f (или --force) команды git add. Однако это имеет смысл, если у вас есть общий шаблон, например *.log, но вы хотите закоммитить конкретный файл:

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

cat .gitignore
# *.log
git add -f debug.log
git commit -m "Force adding debug.log"

В противном случае проще всего задать исключение для общего правила:

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

echo '!debug.log' >> .gitignore

cat .gitignore
#*.log
#!debug.log

git add debug.log
git commit -m "Adding debug.log"

Сохранение игнорируемого файла в stash

Команда git stash берёт ваши незакоммиченные проиндексированные и непроиндексированные изменения, сохраняет их на потом и возвращает рабочую копию в чистое состояние. По умолчанию она сохраняет только изменения отслеживаемых файлов — игнорируемые и неотслеживаемые файлы остаются на месте. Два параметра расширяют эту область:

• git stash --include-untracked (или -u) также сохраняет неотслеживаемые файлы.
• git stash --all (или -a) сохраняет как неотслеживаемые, так и игнорируемые файлы.

git stash --all

Отладка файлов .gitignore

При сложных шаблонах или правилах, распределённых по нескольким файлам .gitignore, бывает трудно понять, какое именно правило скрывает файл. Команда git check-ignore с параметром -v (или --verbose) сообщает точный шаблон, ответственный за игнорирование:

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

git check-ignore -v debug.log
#.gitignore:3:*.log    debug.log

Вывод состоит из четырёх полей, разделённых двоеточиями (и пробелом перед именем файла):

<file containing the pattern>:<line number of the pattern>:<pattern>    <file name>

Таким образом, .gitignore:3:*.log debug.log означает: правило *.log в строке 3 файла .gitignore приводит к тому, что debug.log игнорируется. Если команда ничего не выводит, файл не игнорируется ни одним правилом.

Связанные главы

• git rm — удаление файлов из отслеживания; ключ к игнорированию уже закоммиченного файла.
• git add — индексирование файлов, включая -f для принудительного добавления игнорируемого.
• git stash — сохранение изменений; используйте с --all для включения игнорируемых файлов.
• git config — задание core.excludesFile для глобального списка игнорирования.
• git clean — удаление неотслеживаемых файлов; используйте с -x для удаления и игнорируемых.

Практика