Escrevendo commits melhores no Git
Porque é importante escrever bons commits?
Imagine que você está trabalhando em um projeto, e por algum motivo você precisa consultar o histórico de commits dele, seja pela linha de comando (com git log --oneline), seja por uma interface gráfica, e você se depara com um histórico assim:
1 | e899f75 Recriando os arquivos Customer.cs, Order.cs, Product.cs e remove arquivos ProductOrders.cs e CustomerOrders.cs |
Agora, imagine se em vez do histórico acima, você encontrasse algo assim:
1 | e899f75 Refatora entidades do fluxo de pedidos |
Qual dos dois históricos traz mais claramente e resumidamente as informações do que foi alterado?
No primeiro, não temos padrão nenhum. Hora tem informações de mais, hora de menos. Em vários casos vamos precisar consultar os detalhes do commit para se ter uma ideia do que pode ter sido alterado.
Já no segundo histórico, todas as mensagens seguem o mesmo padrão, expressando em poucas palavras o que foi alterado.
Por exemplo, imagine que seu projeto começou a apresentar problemas para conectar no banco de dados. Em qual dos dois históricos fica mais fácil identificar onde provavelmente o problema foi introduzido no código?
Isso é importante tanto para nosso entendimento (“Quando que eu alterei aquela funcionalidade, mesmo?”), quanto para que outras pessoas se encontrem facilmente em um projeto.
E geralmente as pessoas não dão muito valor a ter um bom histórico de commits até que algo aconteça e elas precisem consultar o histórico de um repositório, e aí já é muito tarde, o histórico já é uma bagunça.
A qualidade do histórico de um projeto no git deve ser de responsabilidade de todo o time, pois qualquer um está sujeito a precisar consultá-lo, e essa padronização deve ser definida em comum acordo com todos.
E para termos uma referência de um bom commit, podemos tomar como exemplo esse abaixo (que é utilizado como exemplo em diversos lugares):
1 | Descrição curta, com 50 caracteres no máximo |
Fica bem construído, não? E não é tão difícil chegar nisso. Para tal, podemos utilizar as 7 regras seguintes.
1- Separe o resumo e o corpo do commit com uma linha em branco
Todo commit no git exige que uma mensagem seja fornecida. Se para explicar e resumir a alteração, uma frase basta, então você pode fazer isso passando o parâmetro -m no próprio comando de commit:
1 | git commit -m 'Cria teste para o repositório de produto' |
Por exemplo, nesse caso, se quem estiver lendo o commit quiser saber quais testes exatamente foram criados, basta utilizar alguns dos comandos do git que vão trazer mais detalhes, como git show, git diff ou git log -p.
Agora, quando o commit precisar de uma explicação mais detalhada, tente sintetizar o máximo possível na frase curta do resumo, e depois coloque mais detalhes no “corpo” do commit. E quando fizer isso, deixe uma linha em branco entre a primeira frase e o restante.
Desta forma, ao utilizar comandos como o git log --oneline ou git rebase, ou consultar o histórico em interfaces gráficas, automaticamente apenas a primeira frase será exibida. E caso quem estiver lendo precisar de mais informações, é possível acessar os detalhes do commit para ver o restante da explicação.
Nesse caso, não vai ser possível escrever a mensagem utilizando o -m, você vai precisar utilizar um editor externo para o commit
2- Limite o resumo do commit a 50 caracteres
O limite de 50 caracteres na primeira linha de resumo não é nenhuma regra rígida, mas é uma dica muito recomendada a ser seguida. Manter a mensagem com poucos caracteres faz quem estiver escrevendo se forçar a resumir da forma mais coesa possível o que se está sendo alterado.
Caso tudo o que você estiver alterando no commit não der para resumir em 50 caracteres, pode ser também um forte indicador de que sejam muitas alterações diferentes sendo enviadas ao mesmo tempo, e o ideal nesse caso pode ser quebrar o commit em mais de um, mantendo eles mais atômicos.
O próprio Github nos faz essa recomendação quando escrevemos uma mensagem de commit muito longa.
Caso, por mais que você tente, ainda seja necessário passar dos 50 caracteres no resumo, garanta que de qualquer forma a mensagem não passará dos 72 caracteres. Com mais de 72 caracteres as mensagens geralmente começam a ser cortadas ao serem exibidas pelas ferramentas, e aí a regra deixa de ser obedecida.
3- Deixe a primeira letra do resumo em maiúsculo
Essa regra é tão simples quando parece. Sempre que escrever uma mensagem de commit, mantenha a primeira letra como maiúscula.
Assim fica Cria nova interface em vez de cria nova interface.
Além de manter uma padronização, fica mais fácil diferenciar a mensagem do commit nas interfaces de texto e nas interfaces gráficas.
4- Não termine o resumo com um ponto final
Também uma regra bem simples. Não utilize um ponto para finalizar a frase definida como resumo. Tendo a coesão e os 50 caracteres como meta, o ponto é um desperdício.
Fica então Altera configuração de banco em vez de Altera configuração de banco..
No corpo da mensagem de commit, pode utilizar o ponto sem problemas.
5- Use linguagem imperativa no resumo do commit
Escreva o resumo do commit iniciando com um verbo no imperativo (como o título de cada uma dessas regras).
Como dica, pense que você deve encaixar a mensagem de commit na seguinte frase: “Quando aplicado, o que esse commit faz?”
Por exemplo, o resumo dos commits devem se encaixar assim:
- Quando aplicado, o que esse commit faz? Corrige o teste de integração
- Quando aplicado, o que esse commit faz? Refatora o cadastro de cliente
- Quando aplicado, o que esse commit faz? Cria a tela de login
Caso contrário, escrevendo de outra forma, a frase fica sem sentido:
- Quando aplicado, o que esse commit faz? Alterei as configurações de banco
- Quando aplicado, o que esse commit faz? Criados os arquivos para nova integração
6- Quebre a linha do corpo do commit em 72 caracteres
Quando estiver escrevendo o corpo do commit, mantenha cada linha com no máximo de 72 caracteres.
Assim, quando a mensagem for exibida, você evita que apareçam quebras de linhas inesperadas, ou que apareçam barras de rolagem, ou que o texto seja cortado automaticamente.
A maioria das interfaces de git vão trabalhar bem com 80 caracteres, mas o limite de 72 permite que as interfaces façam algumas indentações na hora de exibir, deixando o texto mais legível.
Infelizmente, essa quebra de linha usualmente precisa ser feita manualmente nos editores de texto quando você estiver escrevendo a mensagem de commit.
Porém, caso você utilize o Vim, o editor padrão do Git, é possível configurar para que essa quebra seja feita automaticamente (mostrarei como configurar mais abaixo).
Em outros editores será necessário procurar se existe alguma extensão ou configuração para isso, caso contrário, realmente a quebra deverá ser feita manualmente.
7- Descreva no corpo do commit o porquê, não o como
Quando você estiver escrevendo uma mensagem de commit, tenha em mente que, a pessoa que irá ler essa mensagem depois, provavelmente será uma pessoa com conhecimentos técnicos, e que terá acesso ao restante das informações do commit, incluindo o código fonte, quais arquivos foram modificados e quais foram as modificações.
Então não faz sentido você escrever, nem no resumo do commit, nem no corpo, por exemplo, como você corrigiu um problema, qual arquivo que você alterou, qual variável que mudou de valor, ou qualquer outra informação que já não esteja no código fonte que foi alterado naquele commit.
Em vez disso, aproveite este espaço para explicar, conceitualmente, o porquê daquela alteração, qual foi a motivação ou o contexto.
Eu consigo ver nas alterações do commit que uma constante teve seu valor alterado, por exemplo. Agora, eu não consigo saber o que motivou essa alteração, e a mensagem do commit é um ótimo lugar para manter essa informação.
Você também pode utilizar essa mensagem para explicar como aquele pedaço de código funcionava antes, e como ele irá funcionar a partir de agora, sempre focando no porquê aquela alteração foi feita, não como ela foi feita, porque o como já está descrito através das alterações de código que podem ser consultadas.
Conclusão
Tente aplicar essas 7 regras já no seu próximo commit. Discuta com o seu time quais dessas regras podem ser definidas para os seus projetos. Se lembre que essas 7 regras são apenas dicas, e que cada time deve definir suas próprias padronizações.
Se no projeto que você estiver trabalhando existir a cultura de se fazer revisão de código, inclua nessa revisão também a verificação das mensagens de commit. Não precisa barrar um commit porque o comentário dele não ficou bom, mas é sempre bom que essas regras sejam relembradas e seguidas pelo time, porque um histórico do git saudável e padronizado vai ser positivo para todos do projeto.
E para aprofundar seus conhecimentos de git, recomendo o e-book Pro Git, que é gratuito e traz diversas outras dicas e boas práticas sobre o uso de repositórios git.
E claro, como para tudo nessa vida, existe uma tirinha do xkcd sobre isso:
Configurando o Vim para quebrar a linha automaticamente
Caso você tenha feito a instalação padrão do git, muito provavelmente o seu editor padrão de commits é o Vim.
Quem nunca fez um git commit e não precisou pesquisar na internet como faz para sair e voltar para o terminal? E se você nunca passou por isso e não sabe como sair, pode ser <ESC>:q! para sair sem salvar, ou <ESC>:x para salvar e sair.
Mas acredite, o Vim é muito bom editor de textos depois que você pega o jeito, e ele também permite diversas configurações e personalizações.
No caso, vamos fazer uma configuração nele para que, quando você for escrever um commit do git, ele mostre uma guia nos 50 caracteres para você não exagerar no resumo, e que ele também limite o restante da mensagem em 72 caracteres.
Essa configuração irá funcionar não importa qual sistema operacional que você use, seja Windows, Linux ou Mac
Primeiro, caso você ainda não tenha, é necessário criar um arquivo de configuração do Vim.
Esse arquivo usualmente fica no diretório do seu usuário no sistema operacional, e tem o nome de _vimrc.
É possível criar esse arquivo por um terminal de linha de comandos.
Para Windows:
1 | echo '' > ~/_vimrc |
Para Linux ou Mac
1 | touch ~/_vimrc |
Após criar o arquivo, você deve abrí-lo em qualquer editor de texto, e adicionar as seguintes configurações:
1 | autocmd FileType gitcommit set textwidth=72 |
Salve essas configurações, e da próxima vez que você for escrever no Vim uma mensagem de commit utilizando o comando git commit, será exibida uma linha vertical em 50 caracteres, para que você saiba se está passando desse limite no resumo do commit, além de também fazer a quebra de linha automaticamente em 72 caracteres, facilitando a sua vida.
Compartilhe: Twitter - Facebook - LinkedIn