Commits bons: mensagens claras e commits atômicos

1. O que define um “bom commit”?

No Git, o commit é a unidade fundamental de documentação do histórico do projeto. Cada commit representa um ponto de verificação no desenvolvimento, registrando uma alteração intencional no código. Um bom commit não é apenas aquele que funciona — é aquele que comunica eficientemente a intenção da mudança para outros desenvolvedores (e para você mesmo no futuro).

Um commit de qualidade possui três características essenciais:

  • Coeso: contém apenas mudanças relacionadas a um único objetivo
  • Descritivo: explica claramente o que foi feito, por que foi feito e como foi feito
  • Reversível: pode ser desfeito sem afetar funcionalidades não relacionadas

Commits ruins poluem o histórico, dificultam revisões de código (code review), atrapalham ferramentas como git bisect e geram conflitos desnecessários durante merges. Em projetos colaborativos, a qualidade dos commits impacta diretamente a produtividade da equipe.

2. Commits atômicos: um conceito por vez

Atomicidade em commits significa que cada commit deve conter uma única mudança lógica. Se você está trabalhando em uma tarefa que envolve múltiplas alterações distintas, o ideal é dividi-la em commits separados.

Por exemplo, suponha que você precisa:
1. Refatorar uma função existente
2. Corrigir um bug identificado
3. Adicionar uma nova funcionalidade

Em vez de fazer tudo em um commit gigante, você deve criar três commits independentes:

# Commit 1: Refatoração
git add utils/helpers.js
git commit -m "Refatora função de validação para usar early return"

# Commit 2: Correção de bug
git add src/login.js
git commit -m "Corrige falha de autenticação quando token expira"

# Commit 3: Nova funcionalidade
git add src/dashboard.js
git commit -m "Adiciona gráfico de desempenho mensal no dashboard"

Cada commit é autossuficiente, compilável (quando aplicável) e descreve uma alteração completa. Isso permite reverter ou cherry-pick mudanças específicas sem arrastar alterações não relacionadas.

3. Anatomia de uma mensagem de commit clara

A mensagem de commit segue uma estrutura recomendada, amplamente adotada em projetos open source e corporativos:

Título: resumo conciso (até 50 caracteres)

Corpo: explicação detalhada do porquê e como da mudança
- Detalha o problema resolvido
- Explica a abordagem utilizada
- Pode incluir contexto adicional

Rodapé: referências a issues, tarefas ou pull requests

Regras para o título:
- Use o verbo no presente do imperativo: "Adiciona", "Corrige", "Remove", "Atualiza"
- Limite a 50 caracteres (ou no máximo 72)
- Não use ponto final no final
- Seja específico: evite "Correções" ou "Melhorias"

O corpo deve explicar por que a mudança foi feita e como ela resolve o problema, não apenas o que foi alterado (o diff já mostra isso).

4. Boas práticas para escrever mensagens de commit

Use verbos no presente do imperativo:

✅ "Adiciona validação de email no formulário de cadastro"
✅ "Remove dependência não utilizada do lodash"
✅ "Corrige cálculo de imposto para valores acima de R$ 10.000"

Evite mensagens vagas:

❌ "correções"
❌ "várias mudanças"
❌ "wip"
❌ "atualiza"

Referencie issues e tarefas no rodapé:

Adiciona validação de email no formulário de cadastro

Implementa regex para validar formato de email antes do envio.
Inclui mensagem de erro amigável para usuários.

Closes #42
Refs JIRA-1234

5. Ferramentas e comandos para revisar e melhorar commits

Visualizar histórico rapidamente:

git log --oneline --graph --all

Corrigir a mensagem do último commit:

git commit --amend -m "Nova mensagem corrigida"

Reescrever, combinar ou dividir commits com rebase interativo:

git rebase -i HEAD~5

No editor que abrir, você pode usar comandos como:
- pick — manter o commit como está
- reword — alterar a mensagem do commit
- squash — combinar com o commit anterior
- edit — parar para modificar o conteúdo do commit

Exemplo prático de squash:

pick a1b2c3 Adiciona função de validação
squash d4e5f6 Ajusta detalhes na validação
squash g7h8i9 Pequena correção na validação

Após o rebase, você terá um único commit com a funcionalidade completa e uma mensagem limpa.

6. Armadilhas comuns e como evitá-las

Commits "WIP" (work in progress):

Commits com mensagens como "wip", "teste", "debug" poluem o histórico e devem ser evitados. Use branches separadas para trabalho em andamento ou utilize git stash para salvar alterações temporárias sem criar commits.

Misturar mudanças não relacionadas:

Evite alterar formatação, corrigir bugs e adicionar funcionalidades no mesmo commit. Use git add -p (patch mode) para selecionar partes específicas de arquivos modificados:

git add -p src/app.js

Isso permite commit apenas das alterações relevantes para a mudança lógica atual.

Commits enormes:

Commits que alteram dezenas de arquivos com centenas de linhas dificultam revisão e tornam git bisect ineficaz. Prefira commits pequenos e focados, mesmo que exijam mais commits para completar uma tarefa.

7. Relação com outros conceitos da série

Commits atômicos e staging area:

A staging area do Git é a ferramenta ideal para construir commits atômicos. Com git add seletivo (por arquivo ou por hunk), você pode preparar exatamente as mudanças que pertencem a cada commit.

Alinhamento com Conventional Commits:

O padrão Conventional Commits (como feat:, fix:, chore:) complementa as boas práticas de mensagens claras, adicionando um prefixo que indica o tipo de mudança. Isso facilita a geração automática de changelogs e a semântica de versionamento.

Interação com .gitignore:

Um .gitignore bem configurado garante que apenas mudanças relevantes sejam commitadas. Arquivos de build, dependências e configurações locais não devem aparecer no staging, evitando commits acidentais com conteúdo indesejado.

Escrever commits bons é um hábito que se desenvolve com prática e disciplina. O esforço investido em mensagens claras e commits atômicos retorna em forma de histórico legível, revisões mais rápidas e menos conflitos. Comece aplicando essas técnicas no seu próximo commit — seu eu do futuro agradecerá.

Referências