Магические файлы Git

Эндрю Несбитт собрал каталог версионируемых файлов, которые определяют поведение Git у каждого, кто клонирует репозиторий. В отличие от конфигурации в .git/, эти файлы передаются вместе с кодом и начинают действовать автоматически.

Семь основных файлов

.gitignore знаком каждому - это исключение неотслеживаемых файлов по шаблонам. Git считывает правила игнорирования из нескольких мест: файлы .gitignore в отдельных каталогах, .git/info/exclude для локальных шаблонов и глобальный файл игнорирования. Шаблон ** захватывает вложенные каталоги. Частая ловушка: .gitignore влияет только на неотслеживаемые файлы. Если файл уже отслеживается, добавление его в .gitignore ни к чему не приведёт, пока вы не сделаете git rm --cached.

.gitattributes умеет гораздо больше, чем думает большинство команд. В нём настраиваются фильтры LFS (*.psd filter=lfs diff=lfs merge=lfs), нормализация окончаний строк (*.sh text eol=lf), стратегии слияния (package-lock.json merge=ours для авторазрешения конфликтов в lockfile'ах) и переопределения для GitHub Linguist (vendor/* linguist-vendored, чтобы исключить сторонний код из статистики языков). Пометка файлов как binary запрещает Git строить для них diff'ы или выполнять трёхстороннее слияние.

.mailmap сопоставляет разрозненные профили авторов с каноническими. Если разработчик коммитил с трёх разных почтовых адресов, mailmap сведёт их в один для git log, shortlog и blame. При этом графики контрибьюторов на GitHub игнорируют mailmap, так что в веб-интерфейсе дубликаты останутся.

.git-blame-ignore-revs перечисляет коммиты, которые git blame должен пропускать: классический пример - массовое автоформатирование, затронувшее каждый файл, но не изменившее логику. GitHub, GitLab (начиная с 15.4) и Gitea считывают этот файл автоматически. Локально потребуется выполнить git config blame.ignoreRevsFile .git-blame-ignore-revs.

.gitmodules создаётся автоматически командой git submodule add и указывает, где находятся репозитории подмодулей и какую ветку они отслеживают. В git-submodules-as-package-manager описано, почему подмодули плохо подходят на роль механизма зависимостей.

.lfsconfig хранит URL'ы конечных точек Git LFS и параметры передачи данных, благодаря чему LFS работает без ручной настройки каждого клона.

.gitmessage служит шаблоном сообщения коммита, но, в отличие от остальных, требует ручной настройки (git config commit.template .gitmessage) для каждого клона - сам по себе в репозитории он не активируется.

Каталоги конкретных forge-платформ

У каждой git-платформы есть собственный каталог конфигурации для CI-пайплайнов, шаблонов задач (issues) и CODEOWNERS: .github/, .gitlab/, .gitea/, .forgejo/, .bitbucket/. Любопытная деталь - цепочки отката (fallback): Forgejo проверяет .forgejo/, затем .gitea/, затем .github/, а Gitea - сначала .gitea/, затем .github/. SourceHut вообще не использует соглашение о каталогах и читает .build.yml из корня.

Второстепенные соглашения

.gitkeep - общепринятое соглашение сообщества (а не встроенная возможность Git) для принудительного отслеживания пустых каталогов. Файлы .gitconfig внутри репозиториев содержат рекомендуемые настройки, которые разработчики подключают вручную через include, - из соображений безопасности Git не загружает их автоматически. .gitsigners хранит доверенные ключи подписи GPG/SSH. .gitreview настраивает интеграцию с Gerrit. .gitlint задаёт правила линтинга сообщений коммитов.

Несбитт также отмечает, что Jujutsu (.jj/) сосуществует с .git/ и учитывает все эти магические файлы.

Советы авторам инструментов

Если вы разрабатываете инструменты для обхода git-репозиториев, учитывайте эти магические файлы: читайте .gitignore при обходе дерева, проверяйте .gitattributes для выявления бинарных, вендоренных или сгенерированных файлов, используйте .mailmap для сведений об авторах и обрабатывайте .gitmodules для подмодулей. Для формата конфигурации Git ([section "subsection"] key = value) есть парсеры почти во всех языках в составе библиотек для работы с Git.

Связанные соглашения вне Git

.editorconfig стандартизирует отступы и окончания строк в разных редакторах. Файлы версий языков (.ruby-version, .node-version, .python-version, .tool-versions) сообщают менеджерам версий, какую среду выполнения использовать. .dockerignore использует тот же синтаксис, что и .gitignore, но применяется к контексту сборки Docker.

О другом взгляде на внутренности Git - запросах ко всей истории коммитов, блобов и путей через SQL, а не конфигурационные файлы, - читайте в linux-kernel-pgit и pgit. Об инструменте для безопасной перезаписи этой истории вместо простого чтения - в git-history-command.