Como manter commits de reformatação fora do git blame: -w e arquivos ignore-revs

O que é

O git blame anota cada linha com o commit que a alterou por último. Uma execução de formatador, uma mudança de indentação ou a normalização de fins de linha "altera" todas as linhas, e a partir daí o blame aponta para o commit de limpeza em vez de apontar para a alteração que introduziu a lógica. A documentação oferece três ferramentas contra esse problema:

• -w ignora espaços em branco ao comparar a versão do pai com a do filho para decidir de onde vieram as linhas.
• --ignore-rev <rev> trata um commit como se ele nunca tivesse existido; as linhas que ele tocou são atribuídas ao commit anterior que as alterou. --ignore-revs-file <file> lê esses commits de um arquivo, e blame.ignoreRevsFile na configuração aplica um arquivo automaticamente. Com blame.markIgnoredLines, as linhas reatribuídas são marcadas com ?; com blame.markUnblamableLines, as linhas que não podem ser atribuídas a nenhum outro commit são marcadas com *.
• -M detecta linhas movidas ou copiadas dentro de um arquivo, e -C detecta também as linhas movidas ou copiadas de outros arquivos modificados no mesmo commit, de modo que uma refatoração que reposiciona código preserve o autor original.

A documentação do GitHub afirma que um arquivo chamado .git-blame-ignore-revs na raiz do repositório é aplicado automaticamente à sua visualização de blame.

Por que importa

O blame é o caminho que revisores, engenheiros de plantão e agentes usam para encontrar a justificativa de uma linha: a mensagem do commit, o pull request, o ticket. Num histórico em que todas as linhas apontam para "apply black" ou "prettier 3.0", esse rastro se perde justamente nos momentos em que é necessário.

Como aplicar

• Mantenha grandes mudanças mecânicas em commits próprios, sem mais nada dentro, para que possam ser ignoradas por completo.
• Adicione o hash completo de cada um desses commits ao .git-blame-ignore-revs, com uma linha de comentário explicando o motivo, e faça o commit do arquivo.
• Execute git config blame.ignoreRevsFile .git-blame-ignore-revs em cada clone (por meio de um script de setup ou de uma linha de comando documentada); sem isso, a linha de comando não aplica o arquivo.
• Use git blame -w -M -C como padrão nas investigações e -L <start>,<end> para limitar o intervalo.
• Editores e plataformas de hospedagem de código leem o mesmo arquivo; verifique quais deles o fazem antes de depender disso.

Armadilhas

Ignorar um commit que também continha alterações reais esconde essas alterações do blame. Os hashes precisam estar completos, sem abreviação (a documentação de configuração pede um nome de objeto não abreviado por linha), e, depois de uma reescrita do histórico, os IDs listados deixam de corresponder a qualquer commit, de modo que o arquivo precisa ser gerado de novo. git log -S e git bisect não são afetados e continuam encontrando o commit, se necessário.