Os arquivos mágicos do Git

 (nesbitt.io)
45 pontos por GN⁺ 2026-02-24 | 2 comentários | Compartilhar no WhatsApp
  • O Git controla seu comportamento por meio de arquivos específicos dentro do repositório, que não ficam nas configurações internas de .git/, mas são versionados e viajam junto com o código
  • .gitignore, .gitattributes, .lfsconfig, .gitmodules, .mailmap etc. cuidam, respectivamente, de excluir arquivos do rastreamento, definir atributos, configurar LFS, gerenciar submódulos e unificar autores
  • .git-blame-ignore-revs e .gitmessage ajudam a melhorar a colaboração ao permitir ignorar commits de formatação de código e fornecer templates de mensagem de commit
  • GitHub, GitLab, Gitea etc. ampliam funcionalidades como CI/CD e definição de revisores por meio de pastas de configuração específicas da plataforma, como .github/, .gitlab/ e .gitea/
  • Essa estrutura vai além do Git e também aparece em EditorConfig, Docker e ferramentas de gerenciamento de versões de linguagem, formando um ecossistema de configuração automática baseado em dotfiles

Principais arquivos mágicos do Git

  • O Git reconhece vários arquivos especiais como .gitignore, .gitattributes, .lfsconfig, .gitmodules e .mailmap para controlar o comportamento do repositório
    • Esses arquivos não fazem parte das configurações internas de .git/, mas sim de componentes compartilhados e versionados, garantindo comportamento consistente na colaboração

.gitignore

  • Define padrões de arquivos que o Git não deve rastrear
    • Suporta curingas (*.log), diretórios (dist/) e negação (!important.log)
    • É aplicado na ordem .gitignore, .git/info/exclude, configuração global (~/.config/git/ignore)
  • Arquivos já rastreados continuam sendo rastreados mesmo após adicionar ao .gitignore; é possível removê-los com git rm --cached
  • GitHub, GitLab e Gitea permitem fazer commit de arquivos que batem com padrões ignorados sem aviso
  • O GitHub fornece templates de .gitignore por linguagem em seu repositório oficial

.gitattributes

  • Controla filtros, diff, merge, finais de linha e detecção de linguagem por arquivo
    • Ex.: *.psd filter=lfs, *.png binary, *.sh text eol=lf
  • text normaliza finais de linha, binary desativa diff/merge, e merge=ours mantém a versão local em caso de conflito
  • O GitHub Linguist lê .gitattributes para excluir das estatísticas de linguagem, recolher código gerado e excluir documentação
  • Também reconhece .gitattributes por diretório e .git/info/attributes

.lfsconfig

  • Armazena configurações do Git LFS junto com o repositório
    • Permite definir a URL do servidor LFS, número de tentativas de transferência etc.
    • Exemplo: 
      [lfs]
    url = https://lfs.example.com/repo
[lfs "transfer"]
    maxretries = 3
  • .gitattributes define quais arquivos serão tratados por LFS, e .lfsconfig cuida dos detalhes como a localização do servidor
  • Para mover arquivos já commitados para LFS, é necessário o comando git lfs migrate

.gitmodules

  • Armazena informações de configuração de submódulos
  • É criado com git submodule add e consultado em git submodule update
  • Em git clone, os submódulos não são baixados automaticamente; é necessário usar a opção --recurse-submodules
  • Há desvantagens como não permitir rastrear faixas de versão e gerar diretórios .git aninhados

.mailmap

  • Faz a unificação de nomes e e-mails de autores
    • Exemplo: 
      Jane Developer <[email protected]> <[email protected]>
  • Em git log, git shortlog, git blame etc., os nomes passam a aparecer de forma unificada
  • O gráfico de contribuidores do GitHub não respeita mailmap
  • A localização pode ser definida com .mailmap ou a configuração mailmap.file

.git-blame-ignore-revs

  • Define a lista de commits a ignorar no git blame
    • Exclui mudanças sem significado, como execução de formatadores ou aplicação de lint
    • Exemplo: 
      # Ran prettier on entire codebase
a1b2c3d4e5f6g7h8i9j0...
  • Pode ser ativado com git config blame.ignoreRevsFile .git-blame-ignore-revs
  • GitHub, GitLab (15.4+) e Gitea o reconhecem automaticamente
  • Se o arquivo não existir, podem ocorrer erros; por isso, recomenda-se manter um arquivo vazio

.gitmessage

  • Define um template de mensagem de commit
    • Exemplo: 
      # <type>: <subject>
#
# Types: feat, fix, docs, style, refactor, test, chore
  • Requer configuração com git config commit.template .gitmessage
  • Após clonar, a configuração manual ainda é necessária; algumas equipes automatizam isso com husky e afins
  • Como alternativa, é possível usar os hooks commit-msg ou prepare-commit-msg

Pastas de extensão por plataforma

  • GitHub, GitLab, Gitea, Forgejo e Bitbucket usam suas próprias pastas de configuração
    • .github/, .gitlab/, .gitea/, .forgejo/, .bitbucket/
  • Elas incluem workflows de CI/CD, templates de issue/PR, arquivos CODEOWNERS etc.
  • O Forgejo faz fallback na ordem .forgejo/ → .gitea/ → .github/, e o Gitea em .gitea/ → .github/
  • O SourceHut usa .build.yml ou .builds/*.yml

Outros arquivos convencionais

  • .gitkeep: como o Git não rastreia diretórios vazios, é usado como arquivo fictício para manter o diretório
  • .gitconfig: fornece exemplos de configuração de Git por projeto, mas não é carregado automaticamente
  • .gitsigners: gerencia a lista de chaves de assinatura GPG/SSH e pode ser definido com gpg.ssh.allowedSignersFile
  • .gitreview: arquivo de configuração do servidor de revisão de código Gerrit
    • Exemplo: 
      [gerrit]
host=review.opendev.org
port=29418
project=openstack/nova.git
defaultbranch=master
  • .gitlint: define regras de lint para mensagens de commit
    • Exemplo: 
      [general]
ignore=body-is-missing
[title-max-length]
line-length=72
  • .jj/: diretório de estado do Jujutsu, um VCS compatível com Git, que pode coexistir com .git/

O ecossistema de dotfiles além do Git

  • .editorconfig: mantém um estilo de código consistente entre editores
    • Define indentação, finais de linha, codificação, remoção de espaços em branco etc.
    • É suportado por editores principais como VS Code, Vim e Emacs
  • .ruby-version, .node-version, .python-version: lidos por ferramentas de gerenciamento de versão de linguagem (como rbenv, nodenv, pyenv) para fazer troca automática
  • .tool-versions: arquivo de gerenciamento de versões multilinguagem do asdf
  • .dockerignore: define a lista de arquivos a excluir no build do Docker
    • Usa a mesma sintaxe de padrões do .gitignore, melhora a velocidade de build e evita incluir informações sensíveis

Pontos a considerar ao desenvolver ferramentas integradas ao Git

  • Ferramentas que lidam com repositórios Git precisam reconhecer estes arquivos obrigatoriamente
    • .gitignore: aplicar padrões ignorados ao explorar arquivos
    • .gitattributes: distinguir binários e arquivos gerados
    • .mailmap: exibir informações de autor de forma unificada
    • .gitmodules: tratar submódulos
  • O formato dos arquivos de configuração do Git segue a estrutura [section "subsection"] key = value, e pode ser lido e gravado com o comando git config
  • A maioria das bibliotecas Git para diferentes linguagens oferece suporte para fazer parse desse formato

Leituras relacionadas

2 comentários

 
wedding 2026-02-24

Eu não conhecia o gitmessage, mas acho que vou experimentar.
 
GN⁺ 2026-02-24
Comentários do Hacker News
  • Foi dito que GitHub, GitLab e Gitea respeitam o .gitignore e por isso não mostram arquivos ignorados na UI web, mas isso parece uma explicação errada
    Na prática, eles não aparecem porque não fazem parte do repositório. Se um arquivo já foi commitado, eu diria que o correto é ele aparecer
    • Não é isso. Se um arquivo já foi enviado e depois adicionado ao .gitignore, ele continua aparecendo na UI. Isso acontece porque ele ainda faz parte do repo
      Por outro lado, também é possível forçar o commit de um arquivo ignorado desde o início, embora exija um pequeno truque
    • Isso mesmo, o comentário original está errado. O .gitignore só decide se arquivos untracked devem ser ocultados. Se quiser, você pode commitar arquivos ignorados
    • Acho que seria legal existir uma opção tipo showinwebui=(true|false) 😄
    • Senti que esse erro não teria sido escrito por uma pessoa, então parei de ler nessa parte
  • Quero destacar o .git/info/exclude. É um gitignore só local, feito para configurações minhas
    Por exemplo, é útil quando você cria arquivos temporários durante a investigação de um bug e quer mantê-los mesmo ao trocar de branch
    Eu uso um alias de shell assim 
    git-ignore-local () {
  echo "$1" >> .git/info/exclude
}
    Assim dá para adicionar algo facilmente com git-ignore-local myfile.ext
    • Fiz uma versão um pouco mais mágica que funciona mesmo fora do diretório raiz
      No MacOS, basta ajustar a parte do readlink 
      git-ignore-local () {
  root=$(git rev-parse --show-toplevel)
  path=$(readlink -f "$1")
  relpath=$(relpath -m --relative-to="$root" "$path")
  echo "$relpath" >> "${root}.git/info/exclude"
}
      Se você registrar essa função no PATH como git-ignore-local, pode usá-la como git ignore-local
    • O .git/info/exclude também é mencionado logo no começo da explicação do .gitignore
    • Não conhecia esse recurso. Uns arquivos temporários pequenos no meu projeto deixaram meus PRs confusos, e isso parece resolver
  • Se você adicionar /test export-ignore ao .gitattributes, dá para excluir arquivos de teste ao fazer deploy para servidores de produção
    Quando ferramentas de deploy como o Capistrano usam git export, isso é aplicado automaticamente e os arquivos de teste não vão para o servidor
    Isso economiza espaço em disco sem afetar o desenvolvimento
    • É um bom recurso, mas parece que a maioria das pessoas nem conhece direito o git archive
      Quase não vejo isso sendo usado nem em ferramentas básicas de CI. Foi com o Capistrano que vi esse uso pela primeira vez
      Aliás, com a opção export-subst também dá para inserir informações parecidas com git describe diretamente dentro de um arquivo
  • Ao usar jj, eu queria excluir completamente a pasta .jj do repo e de todas as operações do git
    Inclusive para que ela não fosse apagada pelo git clean -xdf. Por enquanto estou resolvendo com um alias temporário git clean -e .jj
    • Dá para usar .git/info/exclude
  • O contributor graph do GitHub não suporta .mailmap
    A discussão relacionada está em GitHub Community Discussion
  • Acho perigosa a configuração package-lock.json merge=ours
    Porque o significado de ours/theirs fica ambíguo em merge ou rebase
    Esse tipo de configuração só faz sentido em ferramentas de merge automatizado, como a branch do git-annex
    Referência: explicação do significado de ours/theirs, estrutura interna do git-annex
  • .git-blame-ignore-revs é um bom recurso, mas deveria ficar na seção de “outras convenções”
    Se ele não estiver configurado no cliente git, então em repositórios sem esse arquivo o git blame falha
    • A partir do git 2.52, dá para usar a opção (:optional) para evitar erro mesmo quando o arquivo não existe
      Há uma explicação em esta resposta no Stack Overflow
  • No geral, acho que a lista está bem organizada
    Só é uma pena que nem todas as ferramentas suportem .mailmap. Por exemplo, o IntelliJ ainda trata isso como bug/pedido de recurso
    Além disso, .git-blame-ignore-revs é apenas uma convenção simples; ele só funciona se você configurar manualmente
  • Um pouco fora do assunto, mas descobri recentemente que o VS Code também reconhece arquivos .ignore
    Eu achava que só o .gitignore valia, mas quando mudei as configurações do ripgrep em .ignore, os resultados da busca mudaram. No fim, fazia sentido
  • O autor do texto também publicou um post de continuação sobre forge-specific repository folders (um tipo de “pastas mágicas”)
    Link: post no nesbitt.io