O que é commit no Git e como escrever um bom commit

“ajustes”, “corrigindo”, “agora vai”, “agora vai mesmo”. Abra o histórico de um projeto de iniciante e é isso que aparece. Parece inofensivo até o dia em que um bug surge em produção e alguém precisa descobrir qual mudança, entre 200 commits com mensagens assim, quebrou o cálculo do frete. Sem mensagens úteis, a investigação que levaria cinco minutos vira uma tarde.

Um commit é um registro permanente do estado do seu projeto num momento, com autor, data e uma mensagem explicando o que mudou. Entender como ele funciona por dentro explica por que a mensagem importa tanto e por que alguns hábitos (commits pequenos, por exemplo) facilitam a vida do time.

O commit começa antes do git commit

O Git trabalha com três áreas, e o commit é o último passo de um fluxo:

1. Diretório de trabalho: os arquivos que você edita normalmente.
2. Área de preparação (staging area ou índice): onde você escolhe, com git add, quais mudanças entram no próximo commit.
3. Repositório: onde o git commit grava de vez aquele conjunto preparado.

git status                 # o que mudou?
git add calculo_frete.py   # prepara só este arquivo
git commit -m "Corrige arredondamento do frete para o Norte"

Antes do primeiro commit numa máquina nova, configure nome e e-mail com git config --global user.name e git config --global user.email. Esses dados vão gravados em cada commit, e é por eles que plataformas como GitHub associam o histórico ao seu perfil.

A área de preparação existe para você separar assuntos. Mexeu no frete e, de passagem, corrigiu um erro de digitação no README? Dá para fazer dois commits, cada um com seu propósito. Com git add -p, dá até para escolher trechos de um mesmo arquivo.

O que o Git grava quando você confirma um commit

Aqui está o detalhe que poucos tutoriais para iniciantes contam: o Git não guarda “diferenças” entre versões. Ele guarda fotografias do projeto. O capítulo sobre objetos internos do Git no livro Pro Git mostra os três tipos de objeto envolvidos:

• Blob: o conteúdo de cada arquivo.
• Tree: a estrutura de pastas, apontando para os blobs.
• Commit: aponta para uma tree, para o commit anterior (o “pai”), e registra autor, data e mensagem.

Arquivos que não mudaram não são copiados de novo: o novo commit aponta para o mesmo blob do commit anterior. Por isso o repositório não explode de tamanho.

Por que cada commit tem aquele código esquisito

Cada objeto recebe um identificador calculado a partir do próprio conteúdo, um hash (historicamente SHA-1, com 40 caracteres hexadecimais, como 3f9a2c1...). Como o commit inclui o hash do commit pai, mudar qualquer coisa no passado muda o hash de tudo que vem depois.

Na prática, isso tem duas consequências que afetam seu dia a dia:

• O histórico é à prova de adulteração silenciosa. Ninguém altera um commit antigo sem que todos os hashes seguintes mudem.
• Reescrever história que já foi enviada causa confusão. Um git commit --amend ou um rebase em commits que colegas já baixaram cria hashes novos, e o histórico deles deixa de bater com o seu. Regra segura: só reescreva commits que ainda não saíram da sua máquina.

Do hash à investigação: onde a mensagem entra

A mensagem é o único pedaço do commit escrito para humanos. E ela é lida em momentos de pressão:

• git log --oneline mostra só a primeira linha de cada commit. Se ela for “ajustes”, a lista é inútil.
• git blame arquivo.py mostra qual commit alterou cada linha. A mensagem desse commit deveria explicar por que aquela linha existe.
• git bisect faz uma busca binária no histórico para achar o commit que introduziu um bug. Commits pequenos e bem descritos tornam o resultado imediatamente útil.

O código mostra o o quê. O diff mostra o como. Só a mensagem guarda o porquê, e é exatamente o que some da memória do time em seis meses.

A anatomia de uma mensagem de commit que ajuda

A convenção mais aceita, descrita em detalhes no texto de Chris Beams sobre como escrever uma mensagem de commit, tem regras simples:

1. Primeira linha (o assunto) com até uns 50 caracteres.
2. Uma linha em branco separando assunto e corpo.
3. Assunto no imperativo: “Corrige”, “Adiciona”, “Remove”. Leia como “Se aplicado, este commit… corrige o arredondamento”.
4. Sem ponto final no assunto.
5. Corpo explicando o porquê e o contexto, quebrado em linhas de uns 72 caracteres.

Compare dois commits para a mesma mudança:

E um exemplo com corpo, quando o porquê não cabe no assunto:

Corrige arredondamento do frete para a região Norte

A transportadora passou a cobrar por faixa de 500 g, e o cálculo
arredondava para o quilo inteiro, cobrando a mais do cliente.
Agora o peso é arredondado para cima em múltiplos de 0,5 kg.

Conventional Commits: quando o time quer padronizar

Muitos projetos adotam a especificação Conventional Commits, que acrescenta um prefixo de tipo ao assunto:

feat: adiciona cálculo de frete por CEP
fix: corrige arredondamento do frete para a região Norte
docs: explica variáveis de ambiente no README
refactor(pagamento): extrai validação de cartão para função própria

A vantagem vai além da estética: ferramentas leem esses prefixos para gerar o changelog e decidir o número da próxima versão automaticamente (um feat sobe a versão menor, um fix sobe a correção). Se o time já usa, siga. Se não usa, não imponha sozinho: a consistência dentro do projeto vale mais que a convenção escolhida.

O tamanho certo de um commit, na prática

Um bom teste: dá para descrever o commit numa frase sem usar “e”? “Adiciona validação de CPF e muda a cor do botão e atualiza dependências” são três commits.

Commits pequenos e atômicos (uma mudança lógica por commit) facilitam revisar, reverter com git revert sem levar junto o que estava certo e encontrar bugs com o bisect. Para outros termos do fluxo do Git, como branch, merge e pull request, consulte o glossário de programação, e veja na documentação oficial do git commit as opções que vão além do -m.

Um hábito que ajuda muito nisso é commitar sempre que um pedaço funciona, mesmo que o recurso inteiro não esteja pronto. Terminou a validação do CEP e os testes passam? Commit. Depois vem a tela. Se algo quebrar no meio do caminho, você volta ao último ponto bom com git restore em vez de desfazer tudo na mão.

O próximo passo é simples: no seu próximo commit, rode git diff --staged antes, leia o que vai entrar e escreva o assunto como se fosse a única pista que alguém terá daqui a um ano. Porque provavelmente será. Para quem trabalha com automação de projetos, o buildbase também mostrou como exportar projetos do Google Jules antes do encerramento do serviço.