.gitignore — Файл, который поможет избежать добавления node_modules

Каждый разработчик хотя бы раз делал это: случайно внес в коммит node_modules, а .env файл, полный API-ключей, или артефакт сборки 200 МБ. Паника реальна. Исправление — мучительно. И всё это было полностью избежимо с помощью одного файла: .gitignore.

Этот гайд объясняет, что такое .gitignore , как это работает, что нужно в него включать, и несколько ловушек, которые ловят даже опытных разработчиков.

Что такое .gitignore?

.gitignore это простой текстовый файл, который сообщает Git, какие файлы и директории исключать из системы контроля версий. Когда Git видит путь, указанный в .gitignore, он как будто этот путь не существует — он не будет включать его, не будет коммитить, и не будет показывать в git status результатах.

Файл находится в корне репозитория, хотя вы также можете разместить проектные .gitignore файлы в поддиректориях. Правила в поддиректории применяются только к этой директории и её поддиректориям.

Почему вам нужно это иметь (краткий вариант)

• Безопасность — сохраняет секреты, API-ключи и пароли из истории Git
• Размер репозитория — предотвращает, чтобы сгенерированные файлы и зависимости не увеличивали размер репозитория
• Уменьшение шума — останавливает файлы конфигурации редактора и мусорные файлы операционной системы от загромождения каждого дифф-файла
• Социальная устойчивость команды — каждый участник клоны чистого репозитория и устанавливает зависимости локально

Как работает синтаксис

Правила просты, но имеют несколько неочевидных особенностей:

• Пустые строки и строки, начинающиеся с # игнорируются (используйте # для комментариев)
• Паттерн без слэша соответствует любому файлу или директории с таким именем в любом месте репозитория: *.log исключает все журналы в любом уровне
• Последующий слэш соответствует только директориям: dist/ исключает директорию, но не файл с именем dist
• Ведущий слэш фиксирует паттерн к корню репозитория: /todo.txt исключает только todo.txt в самой корне
• Двойной звёздочкой (**) соответствует через границы директорий: **/logs соответствует logs/ любые файлы в дереве
• Знак восклицания (!) отменяет паттерн, включает файл, исключённый ранее

Минимальный пример

# Dependencies
node_modules/

# Environment files
.env
.env.local
.env.*.local

# Build output
dist/
build/

# Editor noise
.vscode/
.idea/
*.swp

# OS files
.DS_Store
Thumbs.db

# Logs
*.log
npm-debug.log*

Наиболее распространённые вхождения (и почему они важны)

node_modules/

Это главное. Типичный проект Node.js содержит тысячи файлов в node_modules/ — часто сотни мегабайт. Ни один из них не должен быть в системе контроля версий. Каждый, кто клонирует ваш репозиторий, запускает npm install и пересобирает его локально из package.json. Всегда игнорируйте его.

.env и секретные файлы

Файлы среды содержат пароли баз данных, API-ключи и токены сервисов. Коммит .env — это инцидент безопасности, который может произойти. GitHub сканирует утекшие секреты, но и боты это делают. Игнорируйте файл, коммитите .env.example с placeholder-значениями, чтобы коллеги знали, какие переменные нужно настроить.

dist/ и build/

Компилированные или объединённые выходные данные производятся из исходного кода. Ваш CI-пайплайн пересобирает их при каждом развертывании. Коммит этих артефактов создаёт конфликты слияния и ложные диффы, которые маскируют реальные изменения в коде.

Файлы редактора и ОС

.DS_Store (macOS), Thumbs.db (Windows), .idea/ (JetBrains), .vscode/ (настройки VS Code) — это личные файлы рабочего пространства. Если коммитить их, вы вынуждаете свои настройки на всех других участниках. Используйте глобальный ~/.gitignore_global для машинных настроек, чтобы не приходилось добавлять их в каждый проект.

Глобальный .gitignore: Установите один раз, забудьте

Вы можете настроить глобальный файл игнора, который применяется ко всем репозиториям на вашем устройстве:

git config --global core.excludesfile ~/.gitignore_global

Разместите файлы редактора, мусорные файлы ОС и личные инструменты там. Оставьте проектные .gitignore для вещей, на которые вся команда согласилась игнорировать — например, node_modules/ или dist/.

Ловушка «уже отслеживаемых»

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

Чтобы отключить отслеживание файла, который уже был коммитирован:

# Remove the file from git tracking without deleting it locally
git rm --cached path/to/file

# Or remove a whole directory
git rm -r --cached node_modules/

# Then commit the removal
git commit -m "Stop tracking node_modules"

После этого файл остаётся на диске, но Git игнорирует его в дальнейшем.

Правила отмены: включение файлов обратно

Иногда вы хотите игнорировать директорию, но сохранить один конкретный файл — например, игнорировать config/ но сохранять config/defaults.json включённые:

config/
!config/defaults.json

Одна из проблем: отмена не может отключить файл внутри игнорируемой директории. Git прекращает рекурсивный проход в игнорируемые директории, поэтому правило ! никогда не получает шанса сработать. Вам нужно игнорировать содержимое, а не саму директорию:

# Wrong — Git never sees defaults.json inside an ignored directory
config/
!config/defaults.json

# Right — ignore everything in config/ except defaults.json
config/*
!config/defaults.json

Генерация .gitignore для вашей стек-конфигурации

Вы не обязаны писать это с нуля. gitignore.io (также на gitignore.io) позволяет выбрать язык, фреймворк и редактор, и мгновенно генерировать полноценный файл игнора. GitHub также предлагает официальные шаблоны в репозитории github/gitignore — эти шаблоны хорошо поддерживаемы и покрывают сотни сред.

Для большинства веб-проектов хорошим стартом будет объединение шаблонов для языка (Node, Python, PHP и т.д.), редактора (VS Code, JetBrains) и ОС (macOS, Windows).

Проверка того, что игнорирует Git

Две команды помогают отладить непредвиденное правило игнора:

# See which files are being ignored in the current directory
git status --ignored

# Find out exactly which rule is causing a file to be ignored
git check-ignore -v path/to/file

git check-ignore -v особенно полезна, когда правило не работает так, как ожидается — показывает имя файла, номер строки и паттерн, отвечающий за это.

Быстрый справочник: лист паттернов

Шаблон	Что игнорирует
*.log	Все .log файлы в любом месте
/debug.log	только debug.log в корне
logs/	Любая директория с именем logs
**/logs	logs директория на любом уровне
!important.log	Включить обратно important.log даже если *.log соответствует
doc/*.txt	.txt файлы, непосредственно внутри doc/ (не поддиректории)
doc/**/*.txt	.txt файлы в любом месте под doc/

Вам также может понравиться