5 Dotfiles do Git Que Todo Desenvolvedor Deveria Conhecer

A maioria dos desenvolvedores está familiarizada com .gitignore, mas o ecossistema de configuração do Git vai muito além. Espalhados pelo seu diretório home e raízes de projetos, um punhado de dotfiles essenciais do Git moldam silenciosamente como seu repositório se comporta, como os colaboradores experienciam sua base de código e quão consistentemente o Git funciona entre diferentes máquinas. Compreendê-los evita bugs sutis, históricos confusos e atritos de colaboração.

Aqui estão cinco arquivos de configuração do Git que vale a pena conhecer bem.

1. .gitconfig — Sua Identidade e Comportamento Pessoal no Git

Localizado em: ~/.gitconfig (global) ou .git/config (nível de repositório)

.gitconfig é o arquivo de configuração principal do Git para sua conta de usuário. Ele armazena seu nome, email, editor padrão, aliases e preferências comportamentais. A configuração do Git pode existir em vários níveis: sistema, global, local (repositório) e opcionalmente worktree, com configurações mais específicas sobrescrevendo as mais amplas.

Um padrão prático emprestado de configurações de dotfiles do mundo real: mantenha um ~/.gitconfig para configurações compartilhadas e use diretivas includeIf para carregar sobrescritas específicas da máquina ou do trabalho sem poluir sua configuração principal.

[includeIf "gitdir:~/work/"]
  path = ~/.gitconfig_work

Isso mantém seus dotfiles portáteis enquanto acomoda diferenças por máquina — algo que uma abordagem simples de symlink não consegue lidar de forma limpa. Você pode aprender mais sobre configuração condicional na documentação oficial de configuração do Git.

2. .gitignore — Mantendo Arquivos Não Rastreados Fora do Seu Índice

Localizado em: raiz do projeto, subdiretórios, ou ~/.config/git/ignore (global)

.gitignore afeta apenas arquivos não rastreados. Ele não removerá arquivos já commitados no repositório. Esta é uma fonte comum de confusão — se você precisa parar de rastrear um arquivo commitado, primeiro deve executar git rm --cached <arquivo> antes que a regra de ignore tenha efeito.

Para arquivos que você deseja ignorar globalmente — arquivos swap de editores, .DS_Store, miniaturas do SO — configure um arquivo de ignore global via core.excludesFile no seu .gitconfig:

[core]
  excludesFile = ~/.config/git/ignore

Isso mantém os arquivos .gitignore do projeto limpos e focados em exclusões específicas do projeto, em vez de poluídos com as preferências pessoais de editor de cada desenvolvedor. A documentação oficial do gitignore do Git explica as regras de correspondência e precedência em detalhes.

3. .gitattributes — Mais do Que Apenas Finais de Linha

Localizado em: raiz do projeto (commitado no repositório)

.gitattributes é um dos dotfiles do Git mais subutilizados. Sim, ele lida com normalização de finais de linha (text=auto), mas também controla:

• Comportamento de merge — configure como tipos específicos de arquivos são mesclados
• Manipulação de arquivos binários — informe ao Git para não fazer diff ou merge de certos tipos de arquivo
• Comportamento de exportação — use export-ignore para excluir arquivos de saídas git archive (útil para artefatos de CI)
• Drivers de diff — atribua saída de diff legível para formatos como .docx ou JS minificado

Para projetos frontend, marcar lockfiles ou assets empacotados com atributos apropriados previne conflitos de merge desnecessários e ruído de diff. A gama completa de atributos e comportamentos está descrita na documentação oficial do gitattributes.

4. .git-blame-ignore-revs — Limpando o Blame Após Commits de Formatação

Localizado em: raiz do projeto (commitado no repositório)

Quando você executa um formatador como Prettier ou ESLint em toda uma base de código, git blame torna-se praticamente inútil — cada linha aponta para o commit de formatação em vez do autor original.

.git-blame-ignore-revs resolve isso. Liste os SHAs completos dos commits que você quer que o blame ignore:

# Prettier formatting pass
a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0

Então configure o Git para usá-lo:

git config blame.ignoreRevsFile .git-blame-ignore-revs

O GitHub reconhece este arquivo automaticamente. É uma pequena adição com um impacto significativo na revisão de código e legibilidade do histórico. O comportamento está documentado na documentação oficial do git blame.

5. .mailmap — Normalizando Identidades de Contribuidores

Localizado em: raiz do projeto (commitado no repositório)

Contribuidores mudam endereços de email, usam nomes diferentes em diferentes máquinas, ou fazem commits antes de configurar o Git adequadamente. .mailmap permite que você canonicalize essas identidades ao longo do histórico do seu projeto.

Jane Smith <jane@company.com> <jane@oldmail.com>

Comandos como git shortlog e git log refletirão a identidade corrigida sem modificar o histórico de commits subjacente. Este recurso é especialmente útil para projetos open-source e repositórios de longa duração onde as identidades dos contribuidores evoluem ao longo do tempo. O formato e comportamento estão descritos na documentação oficial do mailmap.

Conclusão

Estes cinco dotfiles do Git — .gitconfig, .gitignore, .gitattributes, .git-blame-ignore-revs e .mailmap — cada um resolve um problema distinto em fluxos de trabalho de desenvolvimento reais. Eles não são apenas sobre preferência pessoal. Vários deles pertencem commitados diretamente ao seu repositório, onde melhoram a experiência para cada contribuidor da equipe. Comece com aqueles que abordam seus pontos de dor mais imediatos, e seu fluxo de trabalho no Git será visivelmente mais limpo por isso.

Perguntas Frequentes

Como faço para parar de rastrear um arquivo que já está commitado mas agora está listado no .gitignore?

Adicionar um arquivo ao .gitignore apenas impede que o Git rastreie novos arquivos não rastreados. Para parar de rastrear um arquivo que já foi commitado, execute git rm --cached seguido do nome do arquivo. Isso o remove do índice sem deletá-lo do seu diretório de trabalho. Depois disso, faça commit da mudança e a regra de ignore será aplicada daqui em diante.

Qual é a diferença entre um .gitignore global e um .gitignore no nível do projeto?

Um arquivo gitignore global, configurado via core.excludesFile no seu .gitconfig, aplica regras de ignore em todos os repositórios da sua máquina. É ideal para artefatos de editores e arquivos gerados pelo SO. Um .gitignore no nível do projeto é commitado no repositório e compartilhado com todos os colaboradores. Use-o para exclusões específicas do projeto como saída de build ou diretórios de dependências.

Preciso usar SHAs completos de commits no .git-blame-ignore-revs?

Sim. O Git requer SHAs de commit completos de 40 caracteres no arquivo .git-blame-ignore-revs. Hashes abreviados não funcionarão e causarão erros ao executar git blame. Você pode recuperar o SHA completo de qualquer commit usando git log ou git rev-parse seguido do hash curto.

O .mailmap afeta o histórico de commits real armazenado no Git?

Não. O arquivo .mailmap não reescreve ou altera nenhum commit. Ele apenas muda como nomes e emails de contribuidores são exibidos na saída de comandos como git shortlog e git log. Os objetos de commit subjacentes permanecem inalterados. É um mapeamento puramente cosmético que normaliza como identidades aparecem em relatórios e estatísticas.