Comandos Git para executar antes de ler o código

• Ao entrar em uma nova base de código, analise o histórico do Git para entender a estrutura do projeto e as áreas de risco e assim definir uma direção de exploração mais eficiente
• Encontre os arquivos alterados com mais frequência no último ano e cruze frequência de mudanças com concentração de bugs para identificar código de alto risco
• Use a distribuição de contribuidores e tendências de atividade para verificar bus factor, lacunas de manutenção e possíveis quebras na transferência de conhecimento
• Acompanhe com commits mensais mudanças no ritmo e no ímpeto de desenvolvimento da equipe e avalie a estabilidade de entrega pela frequência de Revert e Hotfix
• Esses cinco comandos podem ser usados como ferramentas práticas para diagnosticar rapidamente a saúde do projeto antes mesmo de abrir uma única linha de código

---

Cinco comandos Git para executar antes de ler o código

• Ao analisar uma nova base de código, a proposta é diagnosticar a saúde do projeto pelo histórico do Git antes de abrir qualquer arquivo
  • Pelo histórico de commits, dá para entender quem construiu isso, onde os problemas se concentram e quão estável a equipe entrega mudanças

• O que muda com mais frequência?

  • Comando:

    git log --format=format: --name-only --since="1 year ago" | sort | uniq -c | sort -nr | head -20
    

  • Exibe os 20 arquivos mais modificados no último ano
  • Os arquivos do topo muitas vezes são aqueles que a equipe “tem medo de mexer”; quando alta frequência de mudanças (churn) se combina com evasão de ownership, eles se tornam o maior fator de peso da base de código
  • Segundo um estudo da Microsoft Research (2005), métricas baseadas em frequência de mudança preveem defeitos melhor do que métricas de complexidade
  • Cruze os 5 principais arquivos com o comando de concentração de bugs para identificar como maior risco os arquivos que mudam muito e também quebram muito

• Quem construiu este código?

  • Comando:

    git shortlog -sn --no-merges
    

  • Classifica os contribuidores pelo número de commits
  • Se uma única pessoa responde por mais de 60%, há risco de bus factor
  • Se o principal contribuidor não teve atividade nos últimos 6 meses, pode haver uma lacuna de manutenção
  • Se entre 30 contribuidores apenas 3 estiveram ativos no último ano, pode ter ocorrido quebra de conhecimento por rotatividade de desenvolvedores
  • Porém, equipes que usam estratégia de squash-merge podem ter informações de autoria distorcidas em direção a quem fez o merge, então é preciso verificar a estratégia de merge

• Onde os bugs se concentram?

  • Comando:

    git log -i -E --grep="fix|bug|broken" --name-only --format='' | sort | uniq -c | sort -nr | head -20
    

  • Extrai os 20 principais arquivos com ocorrência de bugs com base em commits que contêm palavras-chave relacionadas a bug
  • Compare essa lista com a lista de frequência de mudanças para identificar como código de alto risco os arquivos alterados com frequência e que quebram com frequência
  • A precisão do resultado varia conforme a qualidade das mensagens de commit, mas mesmo como um mapa aproximado de densidade de bugs já é bastante útil

• O projeto está acelerando ou estagnando?

  • Comando:

    git log --format='%ad' --date=format:'%Y-%m' | sort | uniq -c
    

  • Permite visualizar a tendência de atividade pelo número de commits por mês
  • Um ritmo constante indica um projeto saudável
  • Se em um único mês o número de commits cai pela metade, pode haver saída de pessoal-chave
  • Uma queda contínua por 6 a 12 meses sugere perda de ímpeto da equipe, enquanto picos periódicos seguidos de estagnação indicam um padrão de releases em lote
  • Em um caso real, um gráfico de velocidade de commits levou um CTO a reconhecer: “foi nesse ponto que um engenheiro sênior saiu”
  • Esses dados fazem sentido como dados da equipe, não do código

• Com que frequência a equipe está apagando incêndio?

  • Comando:

    git log --oneline --since="1 year ago" | grep -iE 'revert|hotfix|emergency|rollback'
    

  • Mede a frequência de Revert e Hotfix
  • Algumas ocorrências por ano são normais, mas se isso acontece a cada duas semanas, é sinal de desconfiança no processo de deploy
  • Isso pode indicar problemas mais profundos, como testes instáveis, ausência de staging ou procedimentos complexos de rollback
  • Se o resultado for 0, a equipe pode ser estável ou as mensagens de commit podem ser imprecisas
  • Padrões de crise aparecem com clareza, e sua simples presença já ajuda a avaliar a confiabilidade

Conclusão

• Esses cinco comandos podem ser executados em poucos minutos e, antes de abrir uma única linha de código, apontam por onde começar a leitura
• Com isso, em vez de explorar sem rumo no primeiro dia, fica possível fazer uma análise sistemática do código centrada nas áreas problemáticas
• Esse procedimento corresponde à primeira hora de uma auditoria de codebase (codebase audit) e leva ao processo de análise da semana seguinte

[GN⁺]

Comentários do Hacker News

• Compartilharam exemplos no Jujutsu que podem substituir comandos de análise do git
  Dá para verificar com jj log quais arquivos mais mudaram no último ano, os principais contribuidores, onde os bugs se concentram, a vitalidade do projeto e a frequência de correções urgentes
  A sintaxe é mais próxima de programação do que de script de shell, mas há menos flags para decorar

  • Para mim, o jujutsu parece o Nix dos sistemas de controle de versão
    Assim como o Nix é legal, mas adiciona complexidade, o jujutsu me passou essa mesma sensação
    Usei por alguns meses e voltei para o git. O git já está nas mãos e é usado em todo lugar
  • Não entendo como as pessoas conseguem decorar todas essas linguagens de script customizadas
    Eu já fico feliz se lembro do loop de array no jq, então esse tipo de sintaxe realmente não entra na cabeça
  • Tanto os comandos do jj quanto os do git são longos e complexos demais para eu querer decorar
    Se eu fosse usar com frequência, encurtaria com alias
  • Um projeto não está morto só porque não tem commits; isso pode até significar que ele é estável
    Por exemplo, existe uma biblioteca de geração de QR code sem atualização há 10 anos que funciona perfeitamente
    Às vezes fico pensando se deveria adicionar commits inúteis com bot só por isso
  • Não quero programar o git, só quero terminar o trabalho
    Por isso prefiro os tradicionais comandos com pipes do UNIX a ferramentas como o jujutsu
    É pelo mesmo motivo que uso Maven em vez de Gradle

• Achei curioso o autor presumir que desenvolvedores escrevem boas mensagens de commit
  Na prática, a maioria fica no nível de “changed stuff”
  Gente como eu, que considera o log de commits importante, é minoria
  Mensagens de commit geradas por IA podem ajudar bastante com esse problema

  • Isso é um problema de liderança. Um bom líder técnico ou CTO deixa claras as expectativas sobre a qualidade das mensagens de commit
  • Em times que fazem squash ao dar merge no PR, o corpo do PR vira a mensagem de commit, então a qualidade tende a ser melhor
  • Em fluxos com squash & merge, no fim das contas o título do PR é a mensagem principal
    O desenvolvedor pode escrever os commits como quiser, porque depois ninguém lê mesmo
  • Nosso time separa repositórios Core e Non-Core
    Nos Core, revisão de PR e explicações detalhadas são obrigatórias; nos Non-Core, dá para experimentar livremente
    Nos Core, às vezes a mensagem de commit fica 20 vezes maior que o código; nos Non-Core, é algo no nível de “hope this works”
  • Quando desenvolvedores não escrevem mensagens de commit, isso é um problema de cultura
    Na nossa empresa, as pessoas cobram isso umas das outras

• Rodei os comandos em várias codebases e os resultados não batiam com a realidade
  Por exemplo, no resultado de git shortlog -sn --no-merges, às vezes a pessoa com mais commits já tinha saído da empresa
  Ter muitos commits não significa contribuir mais

  • Por isso eu prefiro squash-and-merge
    Commits em excesso ficam só na branch da feature, e o merge para a principal entra limpo
  • Esses comandos são úteis para diagnosticar projetos problemáticos
    Em codebases comuns, costumam gerar resultados sem muito significado
  • Sinceramente, fico em dúvida se o autor realmente rodou os comandos; parece texto escrito por LLM
  • Se um fluxo automatizado usa a credencial de uma única pessoa, as estatísticas podem ficar distorcidas
  • Eu também tenho um número esmagador de commits na codebase central de uma empresa
    Foi porque criei o projeto do zero; hoje outras pessoas fazem commit com mais frequência do que eu

• Achei interessante a ideia de que “o arquivo que mais mudou é o arquivo que as pessoas têm medo de mexer”

  • Parece um paradoxo tipo “o restaurante é tão lotado que ninguém vai”
  • Quando testei, os arquivos mais alterados eram arquivos gerados automaticamente ou coisas chatas como ponto de entrada
  • Esses comandos precisam de aviso
    Tirar conclusões só pelo resultado pode até fazer a pessoa parecer boba
    Na prática, eles só mostram mais ou menos em que funcionalidades se trabalhou no último ano
  • Ver Churn (frequência de mudança) junto com Complexity (complexidade) é muito mais útil
    Onde os dois são altos é a verdadeira zona problemática
    Quando essas áreas se acumulam, começa o papo de “precisamos reescrever o app do zero”
  • Os arquivos que as pessoas temem são os essenciais e complexos
    Todo mundo precisa mexer neles, mas são grandes demais e difíceis de lidar

• Eu criei um alias summary no git para mostrar de uma vez só resumo das branches, número de commits, autores, quantidade de arquivos etc.
  Tirei a ideia de GitAlias/gitalias

  • Fiquei curioso por que isso foi escrito como função no .gitconfig; parece mais simples fazer só um script git-summary
  • Ficar digitando esses comandos toda vez parece texto escrito por IA; quem é experiente reaproveita com alias
  • O script é legal, mas no meu ambiente não existe um comando como log-of-count-and-email
  • Seria bom ter uma man page local para isso

• É preciso adicionar fronteira de palavra (\b) na regex
  Por exemplo, “bug” dentro de “debugger” pode gerar resultado errado
  O exemplo corrigido fica assim
  git log -i -E --grep="\b(fix|fixed|fixes|bug|broken)\b" ...

  • No macOS, \b não é suportado, então em vez de -E é preciso usar a opção de regex Perl -P
    Dá para ajustar para o formato git log -i -P --grep="\b(...)\b"
  • Aqui também usamos a palavra “rollback” com outro sentido, então é preciso filtrar
  • Boa observação, fica bem mais preciso

• Sem squash-merge, a pessoa com mais commits pode acabar sendo justamente o pior desenvolvedor
  Já teve alguém assim no passado: vivia alterando o mesmo arquivo até ser demitido
  O squash é uma boa forma de esconder esse tipo de problema

• Estatísticas simples de número de commits são difíceis de confiar
  Tem gente que só faz commit de código perfeitamente testado, enquanto outros fazem commit a cada linha
  O valor de um commit pode variar 100 vezes de uma pessoa para outra

  • Mas o objetivo do autor era olhar a tendência das mudanças
    A taxa de variação importa mais do que o valor absoluto

• Essa abordagem de análise lembra “Your Code as a Crime Scene”, de Adam Tornhill
  Link do original
  Também se parece com o conceito de Developer’s Legacy Index

  • Eu gostava dos primeiros textos dele sobre C, bom ver isso de novo

• Teria sido melhor se o autor tivesse mostrado diretamente o resultado de cada comando
  Exemplos de saída teriam sido mais convincentes do que explicações

  • Também achei que o texto tinha um leve jeito de coisa escrita por IA, mas ainda assim aprendi cinco comandos, então não foi ruim