Entre em contato

.gitattributes: O arquivo esquecido que pode salvar seu repositório

Quando falamos de Git, quase todo mundo domina .gitignore, estratégias de branching, hooks e pipelines.

Mas existe um arquivo que costuma ser ignorado e que pode evitar uma série de problemas silenciosos em ambientes distribuídos:

.gitattributes

Se você trabalha com times distribuídos, múltiplos sistemas operacionais, CI/CD e automações em cloud, entender .gitattributes deixa de ser opcional e passa a ser obrigatório!!!

Do começo, o que é o .gitattributes?

O .gitattributes é um arquivo versionado que define como o Git deve tratar arquivos específicos dentro do repositório.

Enquanto o .gitignore diz o que não versionar, o .gitattributes define como versionar.

Ele permite controlar:

  • Normalização de line endings (LF vs CRLF)
  • Tratamento de arquivos binários
  • Estratégias de merge
  • Estratégias de diff
  • Integração com Git LFS
  • Exportações para git archive
  • Filtros customizados

O Problema Clássico: Line Endings (Windows vs Linux)

Se você já viu um PR com centenas de linhas alteradas sem mudança real de código, provavelmente foi problema de line ending.

  • Windows → CRLF
  • Linux/macOS → LF

Em ambientes cloud (Docker, Kubernetes, CI Linux), esse detalhe pode:

  • Quebrar scripts shell
  • Invalidar caches
  • Gerar diffs ruidosos
  • Criar conflitos desnecessários

Ou fazer o que já aconteceu comigo mais de uma vez, que é investir várias horas tentando ver o que eu fiz de errado, ler o histórico do Git, ou até mesmo clonar o repositório de novo para ver se foi algo que fiz na minha branch.

De qualquer forma, temos a solução com .gitattributes

* text=auto

Ou de forma mais explícita:

* text=auto eol=lf

Isso força o repositório a armazenar arquivos como LF, independentemente do SO do desenvolvedor.

Para times DevOps, o padrão recomendado é:

* text=auto eol=lf

Isso evita que scripts rodem localmente e falhem no CI.

Tratamento Correto de Arquivos Binários

Sem .gitattributes, o Git pode tentar aplicar diff ou merge textual em arquivos binários.

Exemplo:

*.png binary
*.jpg binary
*.pdf binary

Ou:

*.png -text

Isso evita:

  • Diffs inúteis
  • Merges corrompidos
  • Rebase problemático

Estratégias de Merge Customizadas

Você pode definir que certos arquivos não devem sofrer merge automático.

Exemplo comum em DevOps:

package-lock.json merge=ours

Ou arquivos de ambiente:

.env merge=ours

Isso força o Git a manter a versão da branch atual durante conflitos.

Extremamente útil para:

  • Arquivos gerados automaticamente
  • Arquivos de lock
  • Configurações específicas de ambiente

Git LFS: Indispensável em Cloud

Se seu projeto lida com:

  • Modelos de IA
  • Assets grandes
  • Binários
  • Arquivos > 100MB

Você precisa de Git LFS.

.gitattributes define isso:

*.zip filter=lfs diff=lfs merge=lfs -text
*.mp4 filter=lfs diff=lfs merge=lfs -text

Sem isso, seu repositório cresce descontroladamente e impacta:

  • Clone time
  • CI/CD time
  • Storage costs
  • Cache efficiency

Melhorando o git diff

Você pode configurar diff customizado para linguagens específicas:

*.md diff=markdown
*.json diff=json

Isso melhora a visualização em revisões de código.

Em ambientes corporativos com auditoria forte, isso reduz ruído em PRs.

Export Control com export-ignore

Muito útil para quem publica:

  • Packages
  • SDKs
  • Releases via git archive

Exemplo:

docs/ export-ignore
.github/ export-ignore

Esses arquivos não vão para o pacote exportado.

Excelente para pipelines que geram artefatos de release.

Um .gitattributes Recomendado Para Times Cloud/DevOps

Aqui vai um exemplo base sólido:

# Normalize line endings
* text=auto eol=lf

# Binary files
*.png binary
*.jpg binary
*.jpeg binary
*.gif binary
*.pdf binary

# Shell scripts
*.sh text eol=lf

# Windows scripts
*.bat text eol=crlf

# JSON & YAML
*.json text
*.yml text
*.yaml text

# Git LFS (if used)
*.zip filter=lfs diff=lfs merge=lfs -text
*.mp4 filter=lfs diff=lfs merge=lfs -text

# Ignore on export
docs/ export-ignore
.github/ export-ignore

Impacto Real em DevOps

Ignorar .gitattributes pode gerar:

  • Pipelines quebrando por CRLF
  • Merge conflicts desnecessários
  • Histórico poluído
  • Repositórios inflados
  • Builds inconsistentes

Em ambientes distribuídos e cloud-native, consistência é fundamental.

.gitattributes é uma camada de governança silenciosa do seu código.

Conclusão

Se .gitignore evita sujeira no repositório, .gitattributes evita inconsistência no repositório.

Times maduros em DevOps tratam infraestrutura como código. Repositórios também precisam ser tratados com o mesmo nível de disciplina.

Se seu projeto ainda não tem .gitattributes, não é questão de se vai dar problema, é quando!