Como auditar o histórico de um repositório com git log avançado

1. Fundamentos do git log para auditoria

1.1. Estrutura básica: git log, --oneline, --graph e formatação visual

O comando git log é a ferramenta central para auditoria de repositórios. Sua forma mais básica exibe todos os commits em ordem cronológica reversa. Para auditoria eficiente, combinamos opções que melhoram a legibilidade:

git log --oneline --graph --decorate --all

Esta combinação produz uma árvore visual com hashes abreviados, referências de branches e tags, essencial para entender o fluxo de merges e branches.

1.2. Navegação por intervalos: .., ..., --since, --until

Para auditar períodos específicos ou comparar branches:

# Commits em main que não estão em develop
git log main..develop

# Commits exclusivos de cada branch (diferença simétrica)
git log main...develop

# Intervalo temporal
git log --since="2024-01-01" --until="2024-06-30"

1.3. Filtros por autor: --author, --committer, --no-merges

Auditar contribuições individuais e remover ruído de merges:

git log --author="Maria" --no-merges --oneline
git log --committer="CI Bot" --all

2. Rastreamento de mudanças específicas com filtros avançados

2.1. Busca por mensagens e padrões: --grep, --all-match, --invert-grep

Localizar commits por palavras-chave em mensagens:

# Commits que mencionam "bugfix" na mensagem
git log --grep="bugfix" --oneline

# Commits que contêm TODAS as palavras-chave
git log --grep="security" --grep="patch" --all-match

# Excluir commits de merge
git log --grep="^Merge" --invert-grep

2.2. Filtragem por arquivos e diretórios: -- <path>, --follow, --diff-filter

Rastrear histórico de arquivos específicos:

# Histórico de um arquivo específico
git log --oneline -- src/main.js

# Rastrear renomeações
git log --follow -- src/antigo_nome.js

# Filtrar por tipo de alteração (A=adicionado, M=modificado, D=deletado)
git log --diff-filter=M --oneline

2.3. Localizando commits que introduziram ou removeram termos: -S e -G

A opção pickaxe (-S) encontra commits que alteram a contagem de ocorrências de uma string:

# Commits que adicionaram ou removeram a string "API_KEY"
git log -S"API_KEY" --oneline -p

# Usando regex para padrões mais complexos
git log -G"token\s*=" --oneline

3. Auditoria de alterações em conteúdo com git log -p e --word-diff

3.1. Exibindo diffs completos: -p, --stat, --numstat

Para inspecionar o conteúdo exato das mudanças:

# Diff completo dos últimos 3 commits
git log -p -3

# Estatísticas resumidas
git log --stat --oneline

# Estatísticas numéricas (linhas adicionadas/removidas)
git log --numstat --oneline

3.2. Diferenciação granular: --word-diff, --word-diff-regex

Para mudanças em nível de palavras, não linhas:

git log -p --word-diff --oneline
git log -p --word-diff-regex="[a-zA-Z]+" --oneline

3.3. Limitando saída por quantidade: -n, --skip, --max-count

Controle preciso sobre a quantidade de commits exibidos:

# Últimos 10 commits
git log -10

# Pular os 5 primeiros e mostrar os próximos 3
git log --skip=5 -3

# Commits com pelo menos 2 pais (merges)
git log --min-parents=2

4. Uso de opções de formatação customizada para relatórios

4.1. Formatos predefinidos: --format=oneline, --format=fuller

git log --format=fuller -5
git log --format=reference -5

4.2. Placeholders avançados: %H, %an, %ad, %s, %b

Para relatórios detalhados e personalizados:

git log --format="Commit: %H%nAutor: %an%nData: %ad%nAssunto: %s%nCorpo: %b%n---"

4.3. Geração de logs legíveis por máquina: --pretty=format:"..." com delimitadores

Ideal para exportação e processamento automatizado:

git log --pretty=format:"%H|%an|%ad|%s" --date=short

5. Estratégias de busca reversa e detecção de anomalias

5.1. Encontrando commits quebrados ou regressões: git bisect integrado com git log

O git bisect realiza busca binária para localizar o commit que introduziu um bug. Combinado com git log:

git bisect start
git bisect bad HEAD
git bisect good v1.0
# Após cada teste:
git bisect good/bad
# Ao final, visualizar o commit suspeito:
git log --oneline -1 $(git bisect visualize)

5.2. Identificando merges suspeitos: --first-parent, --ancestry-path

Para seguir apenas o fluxo principal ignorando branches secundários:

# Apenas commits do branch principal (sem merges internos)
git log --first-parent --oneline

# Caminho ancestral entre dois pontos
git log --ancestry-path main..feature-branch

5.3. Auditoria de alterações em branches específicos

git log --branches="feature/*" --oneline
git log --remotes="origin/*" --oneline
git log --tags="v2.*" --oneline

6. Combinando git log com outros comandos para auditoria completa

6.1. Junção com git diff e git show para inspeção detalhada

# Inspecionar um commit específico
git show abc123

# Comparar dois commits
git diff abc123..def456

# Ver o que mudou em um arquivo entre dois commits
git log -p abc123..def456 -- src/main.js

6.2. Uso de git shortlog para sumarizar contribuições por autor

git shortlog -sn --all
git shortlog -e --since="2024-01-01"

6.3. Exportação e análise externa: gerando CSV para ferramentas de parsing

git log --pretty=format:"%H,%an,%ae,%ad,%s" --date=short > auditoria.csv

7. Boas práticas e automação de auditorias recorrentes

7.1. Criando aliases e scripts para auditorias frequentes

Adicione ao ~/.gitconfig:

[alias]
    audit-author = "!f() { git log --author=\"$1\" --since=\"$2\" --until=\"$3\" --format=\"%h %ad %s\" --date=short; }; f"
    audit-file = "!f() { git log --follow --oneline -- \"$1\"; }; f"

Uso: git audit-author "Maria" "2024-01-01" "2024-06-30"

7.2. Uso de hooks e CI para gerar relatórios automáticos

Exemplo de script para CI (GitHub Actions):

#!/bin/bash
# generate-audit-report.sh
git log --since="$(date -d '7 days ago' +%Y-%m-%d)" \
        --format="%h | %an | %ad | %s" \
        --date=short > audit-report-$(date +%Y%m%d).txt

7.3. Documentação de padrões de commit e integração com git notes

Use git notes para adicionar anotações de auditoria a commits específicos:

git notes add -m "Aprovado em auditoria de segurança em 2024-06-15" abc123
git log --show-notes --oneline abc123

Referências