11 Dicas de commits: mensagens, atalhos e quantidade de arquivos

Nessas 11 dicas de commit falo sobre como criar melhores mensagens, commits com muitos ou poucos arquivos, além de atalhos para agilizar o seu trabalho.

Tu te tornas eternamente responsável pela alteração que commitas

"Eu mesmo"

Antes das dicas de commit, gosto de começar pela tradução. Commit pode ser traduzido como:

• "Cometer" no sentido de "fazer", "realizar"
• Ou "comprometer", pois você está em um relacionamento sério com ele

Então para essa relação ter um final feliz, dá uma olhada nessas dicas:

Commit local e commit remoto

A primeira dica de commit pode parecer bem básica. E é.

Mas é interessante entender a diferença entre os commits locais (no seu computador), e os do repositório remoto:

• Se estão iguais, você está up to date
• Se o repositório local tem commits que o remoto não tem, você precisará enviá-los em algum momento com git push
• Se for o oposto, você precisa fazer git pull
• Se existem commits diferentes no histórico, existe uma chance de ocorrer conflitos durante um git pull

É como se você tivesse uma pasta do Google Drive com o seu TCC no computador, sincronizada com a nuvem. A diferença é que a cada sincronização, você precisa criar o pacotinho que se chama commit. E esse pacotinho conta com um ou mais arquivos.

Um ou mais? Quantos?

Quantos arquivos incluir no commit

A resposta para isso é a mesma de sempre: depende!

Tenho a tendência de fazer commits pequenos, ou seja, algo que pode ser explicado e descrito com facilidade. Dessa forma fica mais fácil encontrar uma alteração específica no futuro.

Muitas vezes, mudanças no mesmo arquivo devem pertencer a commits diferentes.

Imagine uma situação onde você modificou o header, o footer e algumas seções da página inicial de um site.

Aqui, os commits podem ser feitos de duas formas:

Exemplo 1: todos os arquivos em apenas um commit

O commit ficaria assim:

[28ea8b4] Alterações no header, footer e seções da home
# Changes to be committed:
#       modified:   header.html
#       modified:   index.html
#       modified:   footer.html
#

Pense que no futuro foi descoberto um bug no footer. E por causa disso você precisará voltar nesse commit para entender a alteração feita.

Quando abrir o commit 28ea8b4, você verá diversos arquivos modificados, inclusive arquivos do header. Isso polui o histórico de commits e atrapalha buscas futuras (que acredite, irão acontecer).

Sem falar que, caso você precise reverter as alterações do footer, as demais também serão revertidas.

Exemplo 2: poucos arquivos divididos em mais commits

Uma das minhas dicas de commit preferidas.

É muito mais feliz fazer commits com menos arquivos. Veja como ficaria a situação anterior:

[28ea8b4] Alterações no header
# Changes to be committed:
#       modified:   header.html

[bfbfff1] Alterações no footer
# Changes to be committed:
#       modified:   footer.html

[c23a7cb] Alterações nas seções da home
# Changes to be committed:
#       modified:   index.html

Se um dia você precisar recuperar as mesmas mudanças feitas no footer, o commit mostrará muito menos modificações.

Além de serem mais fáceis de ler, commits menores são mais fáceis de reverter. Desfazer um bug no header aqui é muito mais simples.

Pronto! Você já sabe quantos arquivos colocar num commit. Veja dicas de como commitar de fato.

Dicas de comandos "Git Commit"

É hora de fechar o pacotinho.

Após realizar algumas alterações e colocar em stage com o git add ., você pode fazer o commit de algumas formas.

Git commit básico

O comando mais básico é:

git commit

Isso vai abrir o seu editor de texto (Nano, Vim, ou o próprio VS Code) para que você digite a mensagem de commit. Assim que você digitar a mensagem, salvar e sair do arquivo, o commit já está feito.

Outra forma é digitar a mensagem de commit logo na linha de comando.:

git commit -m "Minha mensagem de commit"

A parte boa desse comando é que tudo fica pronto numa "tacada" só. Isso elimina o passo de abrir o editor de texto.

"Git add" + Git commit

Com esse comando você adiciona os arquivos e commita ao mesmo tempo:

git commit -am "Minha mensagem de commit"

Mas cuidado! Esse comando não adiciona no commit os arquivos untracked, ou seja, criados após o último commit.

Nesse caso, faça assim:

git add .
# ou git add --all
git commit -m "Minha mensagem de commit"

Caso algum arquivo fique de fora, não se preocupe. E veja a próxima dica de commit:

Commit amend

Aqui, em vez de criar um novo, os arquivos são inseridos no último commit.

Veja um exemplo. Você tem dois commits no histórico:

[28ea8b4] Alterar script.js
# Changes to be committed:
#       modified:   script.js

[bfbfff1] Alterar style.css
# Changes to be committed:
#       modified:   style.css

E está pronto para adicionar dois arquivos no terceiro commit: index.html e about.html. Então executa:

git commit -am "Criar página index e about"

Porém, como o about.html foi criado depois do último commit, ele ficou de fora (esquecido no churrasco). E seu histórico ficou assim:

[28ea8b4] Alterar script.js
# Changes to be committed:
#       modified:   script.js

[bfbfff1] Alterar style.css
# Changes to be committed:
#       modified:   style.css

[c23a7cb] Alterar index.html e about.html
# Changes to be committed:
#       modified:   index.html

Então basta realizar dois passos:

1. Adicionar o about.html no stage
2. E realizar um amend

git add . 
# ou git add --all
# ou git add about.html

git commit --amend

Nesse momento, o editor de texto abrirá a mensagem do último commit (c23a7cb). Após salvar e fechar o arquivo, o about.html será adicionado a ele. E seu histórico ficará assim:

[28ea8b4] Alterar script.js
# Changes to be committed:
#       modified:   script.js

[bfbfff1] Alterar style.css
# Changes to be committed:
#       modified:   style.css

[c23a7cb] Alterar index.html e about.html
# Changes to be committed:
#       modified:   index.html
#       modified:   about.html

Lembra do exemplo que dei do Google Drive? Em vez de criar vários arquivos renomeados daquele jeito constrangedor (trabalho.docx, trabalho_final.docx, trabalho_final_agora_vai.docx), você modifica sempre o mesmo arquivo, e informa em uma mensagem as alterações (e versões).

E é sobre essas mensagens que vou falar agora.

Dicas de como fazer uma boa mensagem de commit

Se você procurar internet a fora, encontrará diversas convenções de como escrever uma boa mensagem de commit.

A dica principal é: não invista tempo desnecessário numa mensagem de commit, se isso não trouxer valor para o projeto.

• Conventional commits
• Semantic version
• Título e descrição do commit

Tudo isso é muito legal, desde que faça sentido para o projeto, time, escopo, etc.

Lembre-se que ao finalizar um commit, você está no espaço tempo perfeito para criar a mensagem dele. Em outras palavras:

• Você entende melhor que seus colegas sobre aquela modificação
• E entende melhor que você mesmo de amanhã, já que as alterações estão frescas na sua memória

Então escreva boas mensagens de commits para seus colegas, e para você do futuro. Ele irá te agradecer.

O que não pode faltar numa mensagem de commit

Expresse o ponto principal com um bom verbo.

Quando escrevo minhas mensagens, esse "ponto principal" é:

• Corrigir: algo está funcionando de um jeito e deveria funcionar de outro (ou nem está funcionando)
• Adicionar: criar ou implementar algo novo. Isso vai de componente, página, até funcionalidades novas
• Remover: uma parte muito satisfatória que é jogar fora o que não se usa mais
• Refatorar: algo mais voltado para boas práticas de código, do que gerar valor para o cliente

Consigo pensar em outras situações como melhorar ou mudar. Só que ambas se encaixam nos conceitos de corrigir ou refatorar. E é claro que verbos sinônimos são muito bem vindos.

Caso você saiba outros verbos que não se encaixam nesses, deixe nos comentários, pois quero saber.

Depois de descobrir o verbo, complemente com a parte do código ou aplicação que você mexeu. Veja mais exemplos:

• Corrigir o modal
• Adicionar um botão
• Remover o componente
• Refatorar código

Como você pode ver, essas mensagens estão "quase" interessantes. O problema é que cada uma delas deixa uma dúvida na cabeça de quem lê.

Que modal? Qual botão? Que componente foi removido? Código?!

Então costumo complementar com um pouco mais de detalhes:

• Corrigir o modal de pagamento que não abre
• Adicionar um botão de CTA sobre o hero na página home
• Remover o componente antigo de vídeo
• Refatorar código da função de parallax

Nesse ponto já considero a mensagem bem clara. Mas e se os detalhes forem grandes demais?

Tamanho da mensagem de commit

50 caracteres.

Essa é uma dica que li várias vezes sobre o limite de uma mensagem de commit. Isso não significa que sua mensagem não possa passar disso. Mas caso ela vá muito além, é um sinal de que seu commit pode estar grande demais.

Nesse caso, recomendo que você adicione menos arquivos ao stage e faça commits menores.

Se mesmo assim a mensagem estiver muito grande, você pode separar ela em título e descrição. Basta deixar a segunda linha vazia:

Remover revalidate do repositório 

O revalidate foi removido das seguintes páginas:
- about
- contact
- index
- [page]
- [slug]
# Please enter the commit message for your changes. Lines starting
# with '#' will be ignored, and an empty message aborts the commit.
#
# On branch main
# Your branch is up to date with 'origin/main'.

E é assim que fica no Github:

Veja agora o que considero mensagens de commit não recomendadas (sendo leviano).

O que não escrever em uma mensagem de commit

Os vilões das dicas de commit.

Em resumo, se faltar alguns dos itens que citei anteriormente, já acho difícil ficar uma boa mensagem.

Caso ela não deixe claro o que aconteceu, vai pelo mesmo caminho.

Após escrever, leia sua mensagem. Se alguma pergunta veio à mente, repense.

• Alterações solicitadas no PR: que alterações são essas?
• Desfazer commit anterior: e o que foi feito no commit anterior? Por que não fazer um git reset?
• Vários commits com a mesma mensagem (ex.: criar página sobre): ué, quantas páginas sobre você criou?
• Coisas aleatórias como m, teste, add, mais um commit: sério, meu consagrado?

Se você não for um grande fã de comandos no terminal, talvez goste de fazer isso usando atalhos do VS Code.

Fazer um commit usando um atalho do VS Code

De uns tempos pra cá comecei a manipular o Git apenas com atalhos.

Achei tão prático, que não dou 1 mês para esquecer os comandos Git.

Para começar, acesso no seu VS Code FIle > Preferences > Keyboard shortcuts (ou use o atalho CTRL + K + S). Na caixa de busca dos atalhos digite:

git.commit

Clique duas vezes sobre a opção Git: Commit e pressione o atalho que queira atribuir a ele.

Ei, psiu!

Ouvi dizer que você gosta de atalhos.

Aqui tem mais 35 dicas de atalhos do VS Code!

Agora ao pressionar o atalho, basta digitar a mensagem na caixa que surge no topo do VS Code:

Se você achar essa caixa pequena demais para digitar uma mensagem, que tal usar uma aba do VS Code para isso?

Editar mensagens do Git pelo VS Code

E com essa dica de commit você vai fechar com chave de ouro.

Você pode editar mensagens como se estivesse em um arquivo de código. Acesse File > Preferences > Settings (ou o atalho CTRL + ,). Na caixa de busca das configurações digite:

Git: use editor As Commit Input

Marque a caixa de seleção, e veja o que acontece ao tentar fazer um commit:

Referências para commits

Mais dicas de commit você pode ver nesses links:

• Conventional Commits
• SemVer
• Creating the perfect commit in git (CSS Tricks)

Callback

Dê preferência para commits menores.

Não esqueça que isso:

git commit -am "Minha mensagem"

É diferente disso:

git add .
git commit -m "Minha mensagem"

Em geral, você usa mais a segunda opção.

Use o git commit --amend sempre que esquecer de adicionar algum arquivo no stage.

Escreva boas mensagens de commit, em outras palavras, curtas e diretas. E não se esqueça de usar o recurso do título + descrição de commit quando necessário.

Deixe nos comentários outras dicas de commit que você costuma usar.

Obrigado pela leitura :)