.gitattributes: fins de linha, diff drivers, merge drivers e export-ignore

O que é

.gitattributes associa padrões de caminho a atributos, com a mesma sintaxe de padrões do .gitignore, e é versionado junto com o código. Os atributos mais usados, conforme descritos na documentação:

• text / text=auto / -text: define se o Git converte os fins de linha no check-in (para LF no repositório). Com text=auto, o Git decide, arquivo por arquivo, se ele é texto.
• eol=lf / eol=crlf: define o fim de linha na árvore de trabalho no checkout; definir eol também ativa text.
• binary: uma macro embutida equivalente a -diff -merge -text.
• diff=<driver>: seleciona um diff driver configurado em [diff "<driver>"], por exemplo xfuncname para escolher a linha de cabeçalho do hunk, ou textconv para converter um formato binário em texto para visualização.
• merge=<driver>: text (three-way merge normal), binary (mantém a nossa versão e deixa o arquivo em conflito), union (reúne as linhas de ambos os lados, sem garantia de ordem) ou um driver personalizado definido em .git/config.
• export-ignore: o caminho fica de fora do git archive; export-subst expande os marcadores $Format:...$ nos arquivos exportados.

Por que importa

Sem uma política versionada, o core.autocrlf de cada desenvolvedor decide o resultado, e fins de linha misturados transformam correções de uma linha em diffs do arquivo inteiro. Diff e merge drivers tornam arquivos gerados ou estruturados revisáveis e reduzem conflitos falsos. O export-ignore mantém testes e configuração de CI fora dos tarballs de release.

Como aplicar

• Comece com * text=auto e depois fixe as exceções: *.sh text eol=lf, *.bat text eol=crlf, *.png binary.
• Depois de adicionar ou alterar regras de fim de linha, execute git add --renormalize . a partir de uma árvore limpa e faça o commit da normalização isoladamente, como mostra o exemplo da documentação.
• Use merge=union em lock files ou changelogs somente se a ordem das linhas realmente não importar; a documentação alerta que o resultado precisa ser verificado.
• Ative os padrões de cabeçalho de hunk embutidos que a documentação lista (*.py diff=python, *.tex diff=tex) para que as revisões mostrem a função que contém a alteração, e defina um driver com xfuncname apenas para linguagens que não tenham um padrão.
• Marque tests/ export-ignore e .github/ export-ignore quando o git archive gerar os releases do seu código-fonte.

Armadilhas

O Git consulta primeiro $GIT_DIR/info/attributes e depois os arquivos .gitattributes, do diretório do caminho até o nível superior; um clone só aplica as novas regras depois de obter o commit que as adiciona, e os arquivos já presentes na árvore de trabalho mantêm os fins de linha antigos até serem renormalizados. Macros como binary só podem ser definidas em arquivos de atributos do nível superior. A saída do textconv é de mão única e não pode ser aplicada como patch. Drivers personalizados ficam na configuração de cada usuário, portanto o atributo sozinho não faz nada em uma máquina que não tenha o driver.