Файл .gitignore в веб-проекте: что исключать из репозитория и зачем

6 минут чтения

`.gitignore` - файл с правилами, по которым Git не предлагает добавлять выбранные файлы и каталоги в репозиторий. В веб-проекте обычно исключают зависимости, результаты сборки, временные данные, локальные настройки и секреты. Перед публикацией проверьте правила командой git check-ignore: `.gitignore` не перестаёт отслеживать файлы, которые уже были добавлены в Git.

Что проверить перед добавлением файлов в Git

Оставьте в репозитории исходный код, файлы манифестов и необходимые команде конфигурации.
Исключите локальные зависимости и результаты сборки, если команда может восстановить их штатными средствами.
Не добавляйте в репозиторий пароли, токены, приватные ключи и персональные настройки.
Убедитесь, что правила соответствуют инструментам и структуре конкретного проекта.
Проверьте исключения до коммита: Git не применяет их задним числом к уже отслеживаемым файлам.

Как `.gitignore` влияет на состав репозитория

Файл `.gitignore` помогает отделить общие для проекта исходники и настройки от локальных или автоматически создаваемых данных. Он подходит для командных репозиториев и личных проектов, где важно не включать в коммиты зависимости, кэш и файлы конкретной рабочей среды.

Не исключайте файлы только потому, что они автоматически генерируются: проверьте, можно ли надёжно восстановить их и не нужны ли они для сборки или развёртывания. Не используйте `.gitignore` как защиту уже опубликованного секрета: удаление пароля из текущей версии файла не убирает его из истории Git.

Соберите список исключений для типичного веб-проекта

Для настройки `.gitignore` для проекта сначала выясните, чем он собирается, где хранятся зависимости и какие файлы создаются локально. Для этого достаточно доступа к рабочей копии репозитория и Git. Просмотрите структуру каталогов, манифесты, инструкции по запуску и настройки сборки. Решая, что добавить в .gitignore для веб-проекта, отталкивайтесь от этой проверки, а не от универсального списка.

Готовый `.gitignore` для веб-разработки можно использовать как основу, но правила нужно сверить с конкретным стеком. Если вы собираетесь скачать шаблон `.gitignore` для веб-проекта, берите его из надёжного источника и проверяйте каждую строку: универсального списка для всех проектов нет.

Сверьте правила для зависимостей, сборки и временных файлов

Перед пошаговой инструкцией подготовьте проект:

Определите используемые языки, фреймворки и сборщики.
Найдите манифесты зависимостей и lock-файлы.
Проверьте, какие каталоги создаются при установке и сборке.
Отметьте локальные настройки и файлы, содержащие секреты.

Создать файл `.gitignore` в проекте можно в корневом каталоге репозитория. Например, откройте редактор в этой папке и создайте файл с точным именем `.gitignore`.

Сохраните важные для команды файлы.
Не исключайте исходный код, конфигурации сборки, документацию и манифесты зависимостей. Lock-файлы обычно оставляют в репозитории, если этого требует принятый в проекте порядок установки.
Добавьте каталоги зависимостей, которые восстанавливаются при установке.
Типичные примеры - node_modules/ для проекта на Node.js и виртуальное окружение Python, если оно создаётся локально. Не исключайте каталог, если он содержит исходники или данные, без которых проект нельзя восстановить.
Исключите результаты сборки и кэш.
Добавьте каталоги, которые генерируются командами сборки или инструментами разработки, например dist/, если проект действительно создаёт его заново. Уточните назначение каждого каталога: в некоторых проектах там могут храниться необходимые статические файлы.
Отделите локальные настройки и временные файлы.
Исключите персональные конфигурации редакторов, журналы и временные данные, если они не нужны команде. Общие настройки форматирования и линтера, напротив, обычно полезно хранить в репозитории.
Проверьте список перед сохранением.
Сопоставьте правила с содержимым проекта и убедитесь, что ни одно из них не скрывает исходники или нужную конфигурацию. Например, правило для dist/ должно соответствовать реальному каталогу результатов сборки.

Категория	Пример правила	Почему исключают	Что проверить
Зависимости	`node_modules/`	Каталог обычно восстанавливается установкой пакетов.	Манифесты и lock-файл должны позволять воспроизвести установку.
Сборка	`dist/`	Содержимое может генерироваться из исходников.	Убедитесь, что каталог не является источником нужных файлов.
Журналы и временные данные	`*.log`	Файлы часто содержат локальный вывод инструментов.	Проверьте, не нужны ли конкретные журналы для тестирования или диагностики.
Локальные переменные окружения	`.env`	Файл может содержать секреты и персональные настройки.	При необходимости добавьте безопасный пример без реальных значений.
Файлы редактора	`.vscode/`	Часть настроек отражает предпочтения конкретного разработчика.	Командные настройки могут быть полезны и должны оцениваться отдельно.

Защитите секреты и локальные настройки от публикации

Проверьте итоговый список перед коммитом:

В `.gitignore` есть правила для локальных файлов с секретами, если проект их использует.
В репозиторий не попали реальные пароли, токены, приватные ключи и сертификаты.
Общие шаблоны конфигурации не содержат действующих секретов.
Файлы локальных настроек не скрывают командные конфигурации, нужные для разработки.
Правила для зависимостей соответствуют манифестам и способу установки.
Каталоги сборки исключаются только тогда, когда их содержимое действительно генерируется.
Проверка Git не показывает, что правило скрывает нужный исходный файл.

Если секрет уже попал в коммит или удалённый репозиторий, немедленно замените или отзовите его. Одного добавления правила в `.gitignore` недостаточно: ранее сохранённое значение может оставаться в истории.

Разберите шаблоны путей, маски и порядок правил

Правило без уточнения пути может совпасть с именем в разных каталогах. Используйте путь от корня, например /dist/, если нужно исключить именно каталог в корне.
Маска *.log затрагивает все подходящие имена. Если нужно исключить только конкретный журнал, укажите его путь, а не широкую маску.
Слеш в конце обозначает каталог. Правило cache/ предназначено для каталогов с таким именем, а не для одиночных файлов.
Правило не перестаёт действовать после добавления файла в Git. Git продолжит отслеживать уже включённый в индекс файл.
Исключение родительского каталога может скрыть вложенные файлы. Для выборочного возврата файла используйте отрицательное правило вида !путь/к/файлу, учитывая, что родительские каталоги тоже должны быть доступны Git.
Последующие правила могут менять результат для совпавшего пути. Размещайте исключения и отрицательные правила в осмысленном порядке и проверяйте итоговую причину.
Не добавляйте в игнорирование всё содержимое типового каталога без проверки. Например, в директории сборки могут лежать файлы, которые команда намеренно хранит в репозитории.

Проверьте исключения на практике и исправьте уже отслеживаемые файлы

Выберите подходящий способ проверки по ситуации:

Проверка конкретного пути. Выполните git check-ignore -v путь/к/файлу, чтобы увидеть, какое правило совпало. Подходит для диагностики неожиданных исключений.
Просмотр состояния перед коммитом. Используйте git status --short и убедитесь, что локальные файлы скрыты, а необходимые исходники остаются видимыми.
Удаление файла из индекса без удаления с диска. Если файл уже отслеживается, выполните git rm --cached путь/к/файлу, затем проверьте состояние и сохраните изменение коммитом. Для каталога используйте подходящий режим команды и сначала убедитесь, что не удаляете рабочие файлы.
Локальное исключение вне общего файла. Для личных файлов, которые не должны менять правила команды, рассмотрите .git/info/exclude. Этот вариант действует только в локальном репозитории.

Если секрет уже отслеживался, сначала обеспечьте его замену или отзыв, затем исключите файл и проверьте состояние репозитория. Изменение индекса само по себе не удаляет прежнее содержимое из истории коммитов.

Разбор спорных ситуаций с `.gitignore`

Нужно ли исключать lock-файл зависимостей?

Обычно его оставляют в репозитории, если он нужен для воспроизводимой установки зависимостей. Следуйте принятому в проекте процессу и не исключайте его по шаблону без проверки.

Почему файл из `.gitignore` всё ещё попадает в коммит?

Вероятно, Git уже отслеживает его. Проверьте состояние репозитория и при необходимости удалите файл только из индекса командой git rm --cached.

Можно ли хранить пример файла `.env`?

Да, если в примере нет действующих секретов и он нужен для настройки проекта. Реальный локальный файл с секретами следует исключить отдельно.

Что делать, если правило скрывает нужный файл?

Уточните правило, ограничив его каталогом или точным путём. Для отдельного исключения из ранее заданной маски можно использовать отрицательное правило, а результат проверить через git check-ignore -v.

Нужно ли исключать папку редактора?

Личные настройки можно исключить, а полезные для всей команды параметры стоит оценить отдельно. Не добавляйте каталог целиком, если в нём хранятся общие конфигурации проекта.

Уберёт ли `.gitignore` опубликованный секрет из истории?

Нет. Отзовите или замените секрет и отдельно разберитесь с историей репозитория; одно правило игнорирования не удаляет прежние коммиты.

Автор материала

Алексей Воронов

Post Views: 0