# .gitignore

_Безопасность · GitLab Knowledge Base_

**TL;DR:** Файл в корне репо со списком паттернов: что Git должен полностью
игнорировать. Не путать с staging: уже tracked файлы .gitignore не
трогает. Главная защита от случайного коммита секретов и мусора.


`.gitignore` - текстовый файл, обычно в корне репозитория. Каждая
строка - паттерн (glob-style). Файлы и директории, подходящие под
паттерн, Git игнорирует: они не показываются в `git status` и не
попадают в `git add .`.

## Базовые правила синтаксиса

```
# Комментарии - со знаком #
*.log               # все .log в любой директории
node_modules/       # директория целиком, в любом месте
/build              # директория build только в корне репо
!important.log      # отрицание: НЕ игнорировать этот файл
src/**/*.pyc        # рекурсивный паттерн через **
```

## Что обязательно в .gitignore

- **Артефакты сборки**: `dist/`, `build/`, `target/`, `*.o`, `*.pyc`.
- **Зависимости**: `node_modules/`, `.venv/`, `vendor/` (если не
  вендорим явно).
- **IDE-файлы**: `.vscode/`, `.idea/`.
- **OS-мусор**: `.DS_Store`, `Thumbs.db`.
- **Секреты**: `.env`, `*.pem`, `*.key`, `secrets.yaml`, `credentials/`.
- **Логи и кэши**: `*.log`, `.cache/`, `__pycache__/`.

Особенно важна последняя категория - секреты. Раз попавший в
коммит секрет считается утёкшим, даже если потом удалён (история
Git показывает прежнее содержимое). Лечение - ротация ключа +
переписывание истории через [git-filter-repo](/courses/git/kb/git-filter-repo.md).

## Что .gitignore НЕ делает

- **Не удаляет уже tracked файл.** Если ты добавил `secrets.yaml` в
  `.gitignore` после того, как уже закоммитил его - Git продолжит
  его отслеживать. Нужно `git rm --cached secrets.yaml` отдельно.
- **Не «защищает» от просмотра.** Файл просто не виден Git'у; в
  диске он остаётся, и любой может его прочитать.
- **Не действует через cache.** Если ты `git add -f secrets.yaml`
  (force), Git добавит несмотря на ignore.

## Где может лежать gitignore

Несколько уровней:

1. **Per-repo:** `.gitignore` в корне, коммитится. Обычно главное.
2. **Per-directory:** `.gitignore` внутри подпапки, действует только
   на её содержимое.
3. **Global (per-user):** `~/.config/git/ignore` или путь в
   `core.excludesFile`. Для личных предпочтений: твой IDE, твоя
   ОС. Не коммитится.
4. **Local-only:** `.git/info/exclude` - игнор только для твоего
   клона, не шарится.

```bash
# Установить global gitignore
git config --global core.excludesFile ~/.gitignore_global
```

В `~/.gitignore_global` обычно класть OS- и IDE-мусор: `.DS_Store`,
`Thumbs.db`, `.vscode/`, `.idea/`. Тогда `.gitignore` в проекте
чище - только проектные паттерны.

## Стандартные шаблоны

Не пиши с нуля. На github.com/github/gitignore лежат шаблоны для
всех языков: `Python.gitignore`, `Node.gitignore`, `Java.gitignore`.
Скопировать в проект и допилить под нужды.

## Если уже закоммитил что не надо

```bash
# Перестать tracking'ать файл, но оставить на диске
git rm --cached path/to/secret

# Добавить в .gitignore
echo "path/to/secret" >> .gitignore

# Закоммитить
git add .gitignore
git commit -m "stop tracking secret"
```

Это убирает файл из будущих коммитов. Но **в истории он остался**,
и любой может его восстановить из старых коммитов. Если это
настоящий секрет - нужно [git-filter-repo](/courses/git/kb/git-filter-repo.md) и ротация ключа.

## Подводные камни

- **`.gitignore` сам в `.gitignore`.** Иногда видишь - это
  случайность, обычно ошибка. `.gitignore` должен коммититься,
  иначе у команды разные ignore-правила.
  - **Локальный игнор vs game.** `.git/info/exclude` - это «только у
  меня». Если используешь - фиксируй явно, иначе через год не
  вспомнишь, что что-то скрыто.
- **Регистр зависит от файловой системы.** На macOS/Windows
  `*.PNG` и `*.png` обычно одно и то же, на Linux - разное. Если
  кросс-платформенный проект - пиши оба варианта.


## Команды

```bash
git rm --cached <file>
```
Перестать tracking, не удаляя файл с диска

```bash
git add -f <file>
```
Добавить файл вопреки .gitignore

```bash
git check-ignore -v <file>
```
Проверить, почему файл игнорируется (показывает паттерн)

```bash
git config --global core.excludesFile ~/.gitignore_global
```
Установить global gitignore для своих файлов


## См. также

- [Поиск секретов в репозитории](/courses/git/kb/secret-scanning.md)
- [git filter-repo: переписывание истории](/courses/git/kb/git-filter-repo.md)