Como escrever uma boa mensagem de commit

A mensagem é o que alguém lê daqui a seis meses, quando um teste quebra e a pergunta é "por que isto mudou?". O Pro Git, o livro oficial do projeto Git, reúne diretrizes de commit que valem para qualquer repositório. Elas são pequenas e se resumem em quatro hábitos.

1. Um commit, uma mudança lógica. Em vez de juntar três assuntos num commit só, divida o trabalho. O livro cita git add --patch para marcar só parte das alterações de um arquivo.
2. Confira os espaços sobrando. Antes do commit, rode git diff --check: ele aponta espaços em branco no fim das linhas e outros descuidos que você não quer eternizar no histórico.
3. Primeira linha curta. O livro sugere um resumo de cerca de 50 caracteres. É uma regra prática, não uma regra do Git: o Git aceita qualquer tamanho.
4. Depois, uma linha em branco e a explicação. O livro sugere quebrar o texto por volta de 72 colunas e descrever a motivação da mudança, comparando com o comportamento anterior. Escreva no imperativo ("corrige o link", em vez de "corrigido" ou "corrige").

Esses números (50 e 72) são recomendações do livro, tratadas aqui como regra prática. O validador de mensagens deste site os mostra como dica, nunca como erro.

Para uma mudança pequena, uma linha basta: git commit -m "docs: corrige o link do README". Para explicar o porquê, use -m mais de uma vez; o Git junta cada -m como um parágrafo separado por linha em branco:

git commit -m "fix: evita travar com arquivo vazio" -m "O comando lia a primeira linha sem conferir se ela existia. Agora devolve uma lista vazia."

Sem o -m, o Git abre o seu editor de texto para você escrever a mensagem inteira.

Se o projeto adota o padrão Conventional Commits, a primeira linha segue o formato tipo(escopo): descrição. O guia de Conventional Commits explica as 16 regras da especificação, e o gerador de mensagem de commit monta o texto e o comando git commit para você. Antes de adotar o padrão em um projeto que não é seu, olhe o histórico e o CONTRIBUTING: use o estilo que já existe.

Na terceira linha, o problema não é o texto, é o tamanho: três assuntos em um commit. Separe com git add --patch ou comitando arquivo por arquivo. Cada commit passa a poder ser entendido, revisado e, se necessário, desfeito sozinho.