Файл .gitignore — полное руководство

ОБЯЗАТЕЛЬНОДЛЯ НОВИЧКОВ

Разработчику Инженеру

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

Без .gitignore репозиторий быстро превращается в свалку: гигабайты node_modules, случайно закоммиченные пароли, конфликты из‑за личных настроек редактора. Для начинающего разработчика умение составить .gitignore — такой же базовый навык, как git init и первый коммит.

См. также: как работать с Git, рекомендации для команды, безопасность .env, README проекта.

---

Содержание

• Зачем нужен .gitignore
• Где создавать файл
• Как Git применяет правила
• Синтаксис и правила
• Что ОБЯЗАТЕЛЬНО игнорировать
• Шаблон .env.example
• Файл уже попал в Git
• Отладка: git check-ignore
• Универсальный базовый шаблон
• Шаблоны по языкам и стекам
• Готовые шаблоны из интернета
• Типичные ошибки
• Работа в команде
• Чек-лист перед первым push

---

.gitignore - файлы вне истории Git

Git отслеживает изменения файлов. Но не каждый файл — часть проекта:

Категория	Примеры	Почему не в Git
Секреты	.env, *.pem, credentials.json	Утечка = взлом, штрафы, увольнение
Зависимости	node_modules/, vendor/	Восстанавливаются из lock-файла
Сборка	dist/, build/, *.exe	Генерируются заново на CI и у коллег
Кэш и логи	*.log, .pytest_cache/	Шум, конфликты, лишний размер
IDE и ОС	.idea/, .vscode/settings.json, Thumbs.db	У каждого разработчика свои

Главное правило безопасности

Секрет, попавший в Git один раз, остаётся в истории навсегда — даже после удаления файла. Пароли нужно ротировать, а не только добавлять строку в .gitignore.

---

Где создавать файл

Расположение	Когда использовать
Корень репозитория .gitignore	Стандарт для 99% проектов
Подпапка frontend/.gitignore	Монорепо: разные правила для разных частей
Глобальный ~/.gitignore_global	Личные файлы ОС/IDE на всех проектах
Локальный .git/info/exclude	Только ваш клон, не для команды

Создание в корне:

cd my-project
touch .gitignore    # Linux/macOS
# или New-Item .gitignore   # PowerShell
git add .gitignore
git commit -m "Добавить .gitignore"

Глобальный ignore (опционально):

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

Пример ~/.gitignore_global:

# Личное — не для репозитория команды
.DS_Store
Thumbs.db
Desktop.ini
*.swp
*~

---

Как Git применяет правила

1. Git читает .gitignore от корня репозитория и из каждой родительской папки до текущего файла.
2. Правило из более глубокой папки не отменяет правило выше — они складываются.
3. Если файл уже отслеживается (был закоммичен раньше), .gitignore на него не действует, пока вы не уберёте его из индекса.
4. Пустые строки и строки, начинающиеся с #, — комментарии.

---

Синтаксис и правила

Каждая непустая строка — один паттерн. Git использует упрощённые glob-правила (не полноценные regex).

Базовые элементы

Символ / конструкция	Значение	Пример	Совпадёт	Не совпадёт
*	Любая строка в сегменте пути	*.log	app.log, logs/error.log	logs (это папка)
?	Один любой символ	file?.txt	file1.txt	file12.txt
[abc]	Один символ из набора	file[12].txt	file1.txt	file3.txt
/ в начале	Только от корня репозитория	/build	build/ в корне	src/build/
/ в конце	Только каталог	logs/	папка logs	файл logs
**	Любая вложенность каталогов	**/temp/	a/temp/, a/b/c/temp/	—
! в начале	Исключение (не игнорировать)	см. ниже	—	—
#	Комментарий	# секреты	—	—
\	Экранирование спецсимвола	\#file	файл #file	—

Примеры паттернов

# Все .log файлы в любом месте
*.log

# Только папка build в корне (не src/build)
/build/

# Любая папка node_modules на любом уровне
node_modules/

# Все .env, кроме примера для команды
.env
.env.*
!.env.example

# Игнорировать всё в папке data, но сохранить .gitkeep
data/*
!data/.gitkeep

# Скомпилированные Python-файлы
__pycache__/
*.py[cod]

Правило «отмены» (!)

Порядок строк важен. Сначала широкое правило, потом узкое исключение:

# Игнорировать все файлы в static/
static/*

# Но отслеживать важный placeholder
!static/.gitkeep

Если родительская папка полностью игнорируется, «раскрыть» файл внутри неё иногда нельзя — Git не заходит в проигнорированный каталог. Тогда игнорируют содержимое через static/*, а не static/.

Пробелы и спецсимволы

• Пробел в имени файла: экранируйте \ или оберните в кавычки в shell; в .gitignore — \ .
• Имена с #: начните строку с \#.

---

Что ОБЯЗАТЕЛЬНО игнорировать

1. Секреты и ключи

.env
.env.local
.env.*.local
*.pem
*.key
*.p12
*.pfx
credentials.json
service-account.json
secrets.yml
secrets.yaml
id_rsa
id_ed25519
*.ppk
.npmrc          # может содержать токен
.pypirc

Вместо секрета — шаблон

В репозиторий кладут .env.example с именами переменных без значений. Подробнее — в разделе ниже и в статье про безопасность .env.

2. Зависимости (восстанавливаются менеджером пакетов)

node_modules/
vendor/          # PHP Composer
bower_components/
.pnpm-store/

3. Артефакты сборки

dist/
build/
out/
target/          # Java Maven/Gradle
bin/
obj/             # .NET
*.o
*.exe
*.dll
*.so
*.dylib

4. Кэш, временные и лог-файлы

*.log
*.tmp
*.temp
.cache/
.turbo/
.parcel-cache/
coverage/
.nyc_output/
htmlcov/
.pytest_cache/
.mypy_cache/
.ruff_cache/

5. Файлы операционной системы

.DS_Store
.AppleDouble
Thumbs.db
ehthumbs.db
Desktop.ini
$RECYCLE.BIN/

6. Настройки IDE (спорно — см. команду)

Часто игнорируют личные настройки, но коммитят общие для команды:

# Обычно игнорируют целиком
.idea/
*.sublime-workspace

# VS Code — личное — игнор, общее — в Git
.vscode/*
!.vscode/extensions.json
!.vscode/launch.json
!.vscode/tasks.json

---

Шаблон .env.example

Файл не игнорируется — он в репозитории и показывает, какие переменные нужны:

# .env.example — коммитим в Git
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
API_KEY=
JWT_SECRET=
DEBUG=true

Разработчик копирует локально:

cp .env.example .env
# затем заполняет .env реальными значениями — .env в .gitignore

---

Файл уже попал в Git

.gitignore не удаляет уже отслеживаемые файлы.

# Убрать из индекса, оставить на диске
git rm --cached .env
git rm --cached -r node_modules/

git add .gitignore
git commit -m "Перестать отслеживать .env и node_modules"

Если секрет уже ушёл на сервер — смените пароль/ключ и при необходимости используйте git filter-repo или поддержку платформы (GitHub Secret Scanning).

---

Отладка — git check-ignore

Проверить, почему файл игнорируется:

git check-ignore -v node_modules/lodash/index.js
# .gitignore:42:node_modules/    node_modules/lodash/index.js

Показать статус всех файлов:

git status --ignored

---

Универсальный базовый шаблон

Подойдёт как старт для любого проекта — дополните блоком под свой язык:

# --- Секреты ---
.env
.env.*
!.env.example
*.pem
*.key
credentials.json

# --- Зависимости и сборка (раскомментируйте нужное по стеку) ---
# node_modules/
# vendor/
# dist/
# build/
# target/
# bin/
# obj/

# --- Логи и кэш ---
*.log
*.tmp
.cache/
coverage/

# --- ОС ---
.DS_Store
Thumbs.db
Desktop.ini

# --- IDE (настройте под команду) ---
.idea/
.vscode/*
!.vscode/extensions.json

---

Шаблоны по языкам и стекам

Node.js / JavaScript / TypeScript

node_modules/
npm-debug.log*
yarn-debug.log*
yarn-error.log*
pnpm-debug.log*
.pnpm-store/

dist/
build/
.next/
out/
.nuxt/
.output/
.vercel/
.turbo/
.parcel-cache/

coverage/
.nyc_output/

*.tsbuildinfo
.env
.env.*
!.env.example

# Локальные override
*.local

Python

__pycache__/
*.py[cod]
*$py.class
*.so
.Python
venv/
.venv/
env/
ENV/
.eggs/
*.egg-info/
.eggs/
dist/
build/
*.egg

.pytest_cache/
.mypy_cache/
.ruff_cache/
htmlcov/
.coverage
.coverage.*
.tox/
.nox/

.env
.env.*
!.env.example

# Jupyter
.ipynb_checkpoints/

# Poetry / uv
.poetry/

Java / Kotlin (Maven и Gradle)

Maven:

target/
pom.xml.tag
pom.xml.releaseBackup
pom.xml.versionsBackup
release.properties
dependency-reduced-pom.xml

*.class
*.jar
*.war
*.ear
hs_err_pid*

.idea/
*.iml
.settings/
.classpath
.project

.env

Gradle:

.gradle/
build/
!gradle/wrapper/gradle-wrapper.jar

*.class
local.properties

.idea/
*.iml

C# / .NET

bin/
obj/
[Dd]ebug/
[Rr]elease/
x64/
x86/
[Aa][Rr][Mm]/
[Aa][Rr][Mm]64/
bld/
[Bb]in/
[Oo]bj/
[Ll]og/
[Ll]ogs/

*.user
*.userosscache
*.suo
*.sln.docstates
*.ncrunch*
_Replaced

.vs/
.idea/

appsettings.Development.json
appsettings.Local.json
secrets.json
*.pfx

TestResults/
coverage/

Go

# Бинарник с именем модуля — часто в корне
/myapp
*.exe
*.exe~
*.dll
*.so
*.dylib
*.test
*.out

vendor/          # если не vendoring в Git

.env
.env.*
!.env.example

Rust

/target/
**/*.rs.bk
Cargo.lock          # для библиотек часто коммитят; для приложений — всегда

.env
.env.*
!.env.example

PHP (Composer)

/vendor/
composer.phar

/node_modules/     # если фронт в том же репо

.env
.env.*
!.env.example

/storage/*.key
/bootstrap/cache/*
!bootstrap/cache/.gitkeep

.phpunit.result.cache
.php-cs-fixer.cache

Ruby

*.gem
*.rbc
/.config
/coverage/
/InstalledFiles
/pkg/
/spec/reports/
/spec/examples.txt
/test/tmp/
/test/version_tmp/
/tmp/

/vendor/bundle/
/.bundle/

.env
.env.*
!.env.example

Flutter / Dart

.dart_tool/
.flutter-plugins
.flutter-plugins-dependencies
.packages
.pub-cache/
.pub/
build/
coverage/

*.iml
.idea/

.env

Android

*.iml
.gradle/
/local.properties
/.idea/
.DS_Store
/build/
/captures/
.externalNativeBuild/
.cxx/

*.apk
*.aab
*.ap_
*.dex

google-services.json   # часто секрет — или используйте CI secrets

iOS / Xcode

build/
DerivedData/
*.pbxuser
!default.pbxuser
*.mode1v3
!default.mode1v3
*.perspectivev3
!default.perspectivev3
xcuserdata/
*.xccheckout
*.moved-aside
*.xcuserstate
*.xcscmblueprint

Pods/                 # если не коммитите CocoaPods
Carthage/Build/

*.ipa
*.dSYM.zip

Docker (дополнение к основному стеку)

docker-compose.override.yml   # локальные порты и секреты
.env
.env.*
!.env.example

---

Готовые шаблоны из интернета

Ресурс	Назначение
github.com/github/gitignore	Официальные шаблоны GitHub по языкам и IDE
gitignore.io	Генератор: выбираете OS + IDE + язык
Шаблон при git init на GitHub/GitLab	Чекбокс «Add .gitignore» при создании репо

При создании репозитория на GitHub можно сразу выбрать шаблон .gitignore — удобно для первого проекта.

---

Типичные ошибки

Ошибка	Последствие	Решение
Добавили в .gitignore после git add	Файл всё ещё в Git	git rm --cached <file>
Закоммитили .env «на минутку»	Секрет в истории	Ротация ключей + удаление из истории
Игнорируют package-lock.json / poetry.lock	У коллег другие версии пакетов	Коммитить lock-файлы
Игнорируют весь .vscode/	У команды разный формат	Коммитить extensions.json, игнорировать settings.json
Копируют чужой .gitignore без чтения	Пропуск нужных правил или лишние	Адаптировать под проект
Паттерн build без /	Может зацепить src/build/ как файл	Использовать /build/ для корня

---

Работа в команде

1. Один .gitignore в корне — источник правды; изменения через pull request.
2. Не дублируйте одни и те же строки в десяти местах без причины.
3. Документируйте неочевидное комментарием: # локальный override Docker, см. README.
4. Pre-commit hooks (gitleaks, detect-secrets) — дополнение, не замена .gitignore.
5. Новый участник: git clone → скопировать .env.example → cp .env.example .env.

---

Чек-лист перед первым push

• .gitignore создан в корне репозитория
• Секреты (.env, ключи) не в git status
• Зависимости (node_modules, venv) не отслеживаются
• Артефакты сборки (dist, target, bin/obj) игнорируются
• Lock-файлы (package-lock.json, Cargo.lock для app) закоммичены
• Есть .env.example без реальных паролей
• git check-ignore -v проверен для спорных путей
• Команда знает, что делать, если секрет всё же утёк

---

Дальше: README проекта · безопасность окружения · шпаргалка Git