.gitattributes

Что делает .gitattributes

Файл .gitattributes указывает Git, как обрабатывать конкретные файлы в зависимости от их пути. Если .gitignore определяет, отслеживать ли файл вообще, то .gitattributes определяет как Git работает с уже отслеживаемыми файлами — как нормализовать переводы строк, как выводить diff, как выполнять слияние и что делать при экспорте. Этот файл хранится в репозитории и коммитится, поэтому все участники проекта получают одинаковое поведение, независимо от личных настроек Git config.

На этой странице рассматриваются формат файла, наиболее распространённые атрибуты (нормализация переводов строк, пометка бинарных файлов, пользовательские драйверы diff/merge и export-ignore), места, где Git ищет файл, а также правила разрешения конфликтующих настроек.

Формат файла

Каждая строка связывает шаблон пути с одним или несколькими атрибутами:

# pattern        attributes
*.txt            text
*.png            binary
*.sh             text eol=lf

Шаблоны следуют тем же правилам glob, что и .gitignore: * соответствует всему, кроме /, ** соответствует вложенным директориям, ведущий / привязывает к директории файла .gitattributes, а строки, начинающиеся с #, — это комментарии. Каждый атрибут после шаблона принимает одну из четырёх форм:

• Установить — text включает атрибут.
• Снять — -text выключает его (ведущий дефис).
• Значение — eol=lf задаёт конкретное значение.
• Не задан — !text сбрасывает любую предыдущую настройку, возвращая поведение Git по умолчанию.

Где Git ищет файл

Большинство проектов хранят единственный .gitattributes в корне репозитория. Однако Git проверяет несколько мест, и правило из вложенной директории переопределяет правило из родительской:

• .gitattributes в любой директории применяется к файлам в этой директории и ниже.
• $GIT_DIR/info/attributes содержит правила, которые не коммитятся (локальные для вашего клона).
• core.attributesFile (как правило, ~/.config/git/attributes) задаёт пользовательские настройки по умолчанию.

Если два правила могут совпасть с одним файлом, побеждает более специфичный путь; а в рамках одного файла побеждает последняя совпавшая строка. Вы можете проверить результат для любого пути с помощью git check-attr:

git check-attr -a README.md
# README.md: text: auto

Нормализация переводов строк

Самое распространённое применение .gitattributes — устранение проблемы «изменилась каждая строка», которая возникает, когда разработчики под Windows и Unix совместно используют репозиторий. Пометка файлов как text позволяет Git нормализовать переводы строк до LF в репозитории и конвертировать их при checkout:

* text=auto
*.sh text eol=lf
*.bat text eol=crlf

text=auto позволяет Git самому определять, какие файлы текстовые, и хранить их с LF в репозитории; явные настройки eol затем принудительно задают конкретный перевод строки при checkout для файлов, которым это нужно (shell-скрипты должны оставаться LF, пакетные файлы Windows — CRLF). Поскольку правила коммитятся, это надёжнее, чем полагаться на настройку core.autocrlf каждого разработчика, которая различается на разных машинах.

Если вы добавляете * text=auto в существующий репозиторий, файлы, уже закоммиченные с CRLF, не будут перенормализованы автоматически. Выполните одноразовую очистку, чтобы следующий коммит исправил это:

git add --renormalize .
git commit -m "Normalize line endings"

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

Указание Git, что файл является бинарным, останавливает попытки показать текстовый diff или выполнить слияние построчно:

*.pdf binary
*.png binary

Атрибут binary — это встроенный макрос, который раскрывается в -text -diff, что отключает конвертацию переводов строк и текстовый diff. Это не даёт Git испортить файл перезаписью переводов строк и предотвращает вывод нечитаемой мешанины байтов в терминал командой git diff.

Для больших бинарных файлов, таких как видео, наборы данных или файлы дизайна, одной пометки «бинарный» недостаточно — они всё равно раздувают историю репозитория. Храните такие файлы с помощью Git LFS, для настройки которого также используется .gitattributes.

Пользовательское поведение diff и merge

.gitattributes может направлять определённые файлы через пользовательские драйверы diff или merge, однако пользовательский драйвер должен быть предварительно определён в вашем Git config — атрибут лишь ссылается на него по имени.

Распространённый случай — генерируемый lock-файл: при конфликте слияния вы хотите сохранить версию своей ветки целиком, а не объединять построчно. Один раз зарегистрируйте драйвер ours, а затем укажите на него для нужного пути:

git config merge.ours.driver true

# .gitattributes
package-lock.json merge=ours

Установка driver в true означает «слияние всегда успешно, и результатом является версия текущей ветки». (Этот атрибут merge=ours на уровне файла не зависит от стратегии слияния -s ours, которая применяется ко всему слиянию целиком.)

Пользовательский драйвер diff работает аналогично и удобен для нетекстовых форматов. В Git также встроены драйверы diff, которые выводят осмысленные заголовки блоков для распространённых языков, чтобы diff показывал, какая функция изменилась:

*.c diff=cpp
*.py diff=python

Смотрите раздел git diff о том, как эти драйверы влияют на вывод.

Export-ignore

Когда кто-то загружает архив релиза через git archive, обычно нужно исключить из него файлы для разработки. Именно для этого служит атрибут export-ignore:

/tests       export-ignore
/.github     export-ignore
.gitattributes export-ignore

Это позволяет исключить из архива, создаваемого командой git archive, тестовые наборы, конфигурацию CI и файлы редактора, чтобы пользователи загружали только то, что им нужно. Связанный атрибут export-subst раскрывает плейсхолдеры вида $Format:%H$ внутри экспортируемых файлов, чтобы архив мог содержать запись о коммите, из которого он был создан.

Распространённые атрибуты

Когда использовать

Обращайтесь к .gitattributes всякий раз, когда поведение Git на уровне отдельных файлов должно быть одинаковым для всех участников команды, а не зависеть от локальных настроек. Основные преимущества — нормализация переводов строк в смешанной команде Windows/Unix, отключение бесполезного diff для бинарных файлов и оптимизация архивов релизов. Продвинутые возможности — пользовательские драйверы merge/diff и Git LFS — решают конкретные проблемы по мере их возникновения в проекте. Начните с * text=auto и добавляйте правила по мере появления реальных проблем.

Практика