Artigo original escrito por Bolaji Ayodeji
Artigo original: How to Write Good Commit Messages: A Practical Git Guide
Traduzido e adaptado por Daniel Rosa

Para criar um histórico de revisão útil, as equipes primeiro devem concordar quanto a uma convenção a ser utilizada nas mensagens de commit. Isso também se aplica a projetos pessoais.

Recentemente, no Hashnode (em inglês) escrevi: "Que convenção nas mensagens de commit você usa no trabalho?" Recebi ótimas respostas dos usuários explicando as convenções que eles usam no trabalho e para seus projetos pessoais.

Neste artigo, tratarei de como escrever boas mensagens de commit e do motivo de serem necessárias.

Observação: Este artigo foi publicado primeiramente no blog do autor aqui.

Introdução ao controle de versões com o Git

O software de controle de versão é uma parte essencial das práticas do desenvolvedor de software nos dias de hoje.

O Git é, com certeza, o sistema de controle de versão mais amplamente usado no mundo. Ele é um projeto de código aberto, distribuído e mantido ativamente, desenvolvido em 2005 por Linus Torvalds, o famoso criador do kernel do sistema operacional Linux.

Conheceu o Git há pouco tempo? Confira o guia oficial do iniciante (em inglês) ou ainda esta apresentação de slides (em inglês) de uma palestra do autor do texto.

O que é uma mensagem de commit?

O comando commit é usado para salvar alterações em um repositório local após fazer o staging no Git. No entanto, antes de poder salvar as alterações no Git, você precisa informar ao Git quais alterações você deseja salvar, pois é possível que você tenha feito milhares de edições. Uma ótima maneira de fazer isso é adicionar uma mensagem de commit para identificar suas alterações.

Opções do comando commit

  • -m

Esta opção define a mensagem de commit.

git add static/admin/config.yml
git commit -m "Setup multiple roles for netlify-cms git gateway"
  • -a ou --all

Esta opção faz automaticamente o commit de todos os arquivos (incluindo os novos) rastreados, modificados ou excluídos.

git commit -a -m "Add a new role for netlify-cms git gateway"
  • --amend

Esta opção reescreve o último commit com qualquer alteração que tenha passado por staging no momento ou com uma nova mensagem de commit, devendo ser realizado apenas em commits cujo push ainda não foi realizado em um repositório remoto.

git add .
git commit --amend -m "Update roles for netlify-cms git gateway"

Por que eu devo escrever boas mensagens de commit?

Você pode até dizer que "é só um projeto pessoal." Sim, você trabalha sozinho agora, mas e quando você trabalhar com uma equipe ou contribuir com o código aberto?

Uma mensagem de commit para o Git bem redigida é a melhor maneira de comunicar o contexto de uma alteração para outros desenvolvedores que estejam trabalhando no projeto. De fato, até para o seu "eu" do futuro.

Você já tentou executar o comando git log em um de seus projetos antigos para ver as mensagens de commit "estranhas" que você usava desde o início de um projeto? Pode ser difícil entender a razão pela qual algumas alterações foram feitas no passado. Você vai desejar ter lido esse artigo antes :).

As mensagens de commit podem comunicar adequadamente o motivo de uma alteração ter sido feita. Entender isso torna o desenvolvimento e a colaboração mais eficazes.

Como escrever mensagens de commit com o Git

Antes, eu usava apenas git commit -m "Fix X to allow Y to use Z" em meus projetos pessoais com apenas um assunto e nenhuma descrição adicional. Isso é ótimo para repares pequenos e claros, como git commit -m "Fix typo in README.md, mas nos casos de alterações mais extensas, pode ser necessário adicionar mais detalhes.

Método do editor

Executar git commit sem uma mensagem ou opção abrirá um editor de texto padrão para escrever uma mensagem de commit.

Para configurar seu editor "padrão":

git config --global core.editor nano

Esse comando vai configurar o Git para usar o nano como seu editor padrão. Substitua "nano" por "emacs", "vim" ou seja qual for o seu editor favorito.

No editor aberto, a primeira linha é o assunto (descrição breve), deixe uma linha em branco depois dela e escreva todo o resto na descrição estendida (corpo do texto).

<Resumo da(s) mudança(s) em cerca de 50 caracteres ou menos>

<Descrição explicativa mais detalhada da alteração, se possível, em até 72
caracteres>

Método da linha de comando

git commit -m "Assunto" -m "Descrição..."

A primeira opção de -m é o assunto (descrição breve) e depois vem a descrição estendida (corpo do texto).

Como escrever boas mensagens de commit

Existem várias convenções usadas por equipes diferentes para escrever boas mensagens de commit. Descreverei aqui apenas algumas regras gerais e dicas para escrever mensagens de commit – você tem de decidir qual convenção deseja seguir. Se trabalha para uma empresa ou se contribui para o código aberto, é preciso se adaptar a convenção de lá :).

Para fins de consistência, você pode usar uma convenção para o trabalho e uma para seus projetos pessoais, já que, em algum momento, você pode trocar de emprego e a convenção também pode mudar.

Não se esqueça de conferir essa thread (em inglês) para ver algumas convenções de mensagens de commit incríveis ou para adicionar a sua para ajudar outras pessoas a fazer escolhas nesse sentido .

Aqui temos um ótimo modelo de boas mensagens de commit, escrito originalmente por Tim Pope

Resumo com Capitalização e Breve (no Máximo, 50 Caracteres)

Texto explicativo mais detalhado, se necessário. Deixe-o com, cerca de 72
caracteres. Em alguns contextos, a primeira linha é tratada como o assunto de um e-mail e o resto do text como o corpo. A linha em branco separando o resumo do corpo é fundamental (a menos que você não escreva uma descrição detalhada); ferramentas como o rebase podem se confundir se você executar ambas em conjunto.

Escreva sua mensagem de commit no imperativo: "Consertar o bug" em vez de "Bug consertado" ou "Conserta o bug". Esta convenção corresponde às mensagens de commit geradas por comandos como o git merge e o git revert.

Outros parágrafos vêm após linhas em branco.

- Colocar a descrição em itens está ok

- Tipicamente, um hífen ou um asterisco é usado como bullet point (marcação de itens), seguido de um único espaço, envolvido por linhas em branco, mas as convenções variam

- Use indentação

Se você usar um rastreados de questões/problemas (issues, em inglês), adicione uma referência a eles ao final, dessa maneira:

Resolve a issue nº 123

Parece ótimo, não é? Aqui está uma forma de fazer com que seus commits também sejam ótimos:

  1. Especifique o tipo de commit:
  • feat: uma nova feature (recurso) que você está adicionando a uma aplicação específica
  • fix: a resolução de um bug
  • style: recurso e atualizações relacionadas à estilização
  • refactor: refatoração de uma seção específica da base de código
  • test: tudo o que for relacionado a testes
  • docs: tudo o que for relacionado à documentação
  • chore: manutenção regular do código. (Você também pode usar emojis para representar os tipos de commit)
  1. Separe o assunto do corpo do texto com uma linha em branco
  2. Sua mensagem de commit não deve ter erros espaços em branco em excesso ou palavras sem espaços entre elas
  3. Remova a pontuação desnecessária
  4. Não termine uma linha de assunto com um ponto
  5. Capitalize as palavras da linha do assunto e a primeira palavra de cada parágrafo
  6. Use o modo imperativo na linha de assunto
  7. Use o corpo do texto para explicar quais mudanças você fez e o motivo de tê-las feito.
  8. Não presuma que o revisor entende qual era o problema original. Não se esqueça de descrever o problema.
  9. Não pense que seu código é autoexplicativo
  10. Siga a convenção de commit definida por sua equipe

Conclusão

A parte mais importante de uma mensagem de commit é o fato de que ela deve ser clara e significativa. No final, escrever boas mensagens de commit demonstra que você é um bom colaborador. Os benefícios de escrever boas mensagens de commit não se limitam apenas à sua equipe, mas se estendem a você mesmo e a colaboradores no futuro.

Quer aprender mais sobre o Git e se tornar um "controlador de versões profissional"? Confira esses ótimos recursos (em inglês):