Um guia para entender a importância das mensagens de commit e como escrevê-las bem.
Pode te ajudar a aprender o que é um commit, entender porque é importante escrever boas mensagens usando boas práticas e conhecer dicas para planejar e (re)escrever o seu histórico de commits.
Observações: Apesar da versão em português ter sido escrita antes da versão em inglês, a versão inglês contém alguns textos que estão mais detalhados, assim como melhor referenciamento de fontes.
Em termos simples, o commit é uma espécie de snapshot dos seus arquivos locais gravado localmente no seu repositório. Ao contrário do que se pensa, o git não armazena apenas as diferenças e sim a cópia completa dos arquivos. No caso de arquivos que não mudaram de um commit para o outro, é gravada uma referência ao arquivo gerado no último snapshot.
A imagem abaixo mostra como o git armazena dados ao longo do tempo com uma versão para cada commit:
- Facilita e agiliza o code review
- Ajuda no entendimento do que está acontecendo
- Explica os porquês ocultos que não podem ser explicados somente em código
- Facilita a solução de problemas e a depuração garantindo que futuros codificadores entendam por que e como as mudanças foram feitas
# Good
Use InventoryBackendPool to retrieve inventory backend
# Bad
Used InventoryBackendPool to retrieve inventory backend
Por que!?
A mensagem de commit diz o que ele faz, não o que foi feito.
Regrinha de ouro para mensagens:
If applied, this commit will: <commit message>
# Good
If applied, this commit will: Use InventoryBackendPool to retrieve inventory backend
# Bad
If applied, this commit will: Used InventoryBackendPool to retrieve inventory backend
# Good
Add `use` method to Credit model
# Bad
add `use` method to Credit model
É uma regra bem discutível e a menos importante pra mim. O motivo de escolher começar com letra maiúscula é simplesmente porque é assim que se começa uma frase em qualquer texto.
# Good
Add `use` method to Credit model
# Bad
Add `use` method
# Good
Increase left padding between textbox and layout frame
# Bad
Adjust css
# Good
Fix method name of InventoryBackend child classes
Classes derived from InventoryBackend were not
respecting the base class interface.
It worked because cart was calling the backend implementation
incorrectly.
# Good
Serialize and deserialize credits to json in Cart
Convert the Credit instances to dict for two main reasons:
- Pickle relies on file path for classes and we do not want to break up
everything if a refactor is needed
- Dict and built-in types are picklable by default
# Good
Add `use` method to Credit
Change from namedtuple to class because we need to
setup a new attribute (in_use_amount) with a new value
O título e o corpo da mensagem são separados por uma linha em branco. Linhas em branco adicionais são consideradas como parte do corpo.
Caracteres como - e * e ` são elementos comuns para melhorar a leitura.
# Bad
Fix this
Fix stuff
Agora vai
Change stuff
Adjust css
Recomenda-se 50 caracteres para o título e por volta de 72 para o corpo.
# Good
ababab Add `use` method to Credit model
efefef Use InventoryBackendPool to retrieve inventory backend
bebebe Fix method name of InventoryBackend child classes
# Good
ababab Adiciona o método `use` ao model Credit
efefef Usa o InventoryBackendPool para recuperar o backend de estoque
bebebe Corrige nome de método na classe InventoryBackend
# Bad
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
efefef Add `use` method to Credit model
cdcdcd Agora vai
Summarize changes in around 50 characters or less
More detailed explanatory text, if necessary. Wrap it to about 72
characters or so. In some contexts, the first line is treated as the
subject of the commit and the rest of the text as the body. The
blank line separating the summary from the body is critical (unless
you omit the body entirely); various tools like `log`, `shortlog`
and `rebase` can get confused if you run the two together.
Explain the problem that this commit is solving. Focus on why you
are making this change as opposed to how (the code explains that).
Are there side effects or other unintuitive consequences of this
change? Here's the place to explain them.
Further paragraphs come after blank lines.
- Bullet points are okay, too
- Typically a hyphen or asterisk is used for the bullet, preceded
by a single space, with blank lines in between, but conventions
vary here
If you use an issue tracker, put references to them at the bottom,
like this:
Resolves: #123
See also: #456, #789
TL;DR: Aplica os commits do seu branch, um a um, sobre o branch de base, gerando uma nova árvore
TL;DR: Cria um novo commit, chamado de Merge commit, com as diferenças entre a sua árvore e a árvore de base
Eu particularmente prefiro o rebase, alguns motivos incluem:
- Deixa o histórico mais "limpo", sem commits de merge desnecessários espalhados nele
- What you see is what you get, i.e., em um code review você está vendo o diff real entre o master e o branch
- Os conflitos mais complexos são resolvidos pelo commiter e ficam dentro de um commit, que tem mensagem e propósito
- Ninguém olha o conteúdo dos commits de merge e nisso que mora o perigo
Squash é o processo de pegar uma série de commits e juntá-los em um commit só.
É útil em diversas situações, como por exemplo:
- Muitos commits adicionais sem contexto (correção de typos, formatação, coisas esquecidas)
- Mudanças que estão em commits separados que fariam mais sentido parte de um só
- Commits WIP
Evite rebase e squash em commits públicos ou em branches compartilhadas que outras pessoas possam ter trabalhado. Rebase e squash reescrevem a história sobrescrevendo commits existentes, fazendo isso em commits que existam em branches compartilhadas (i.e., commits enviados para repositórios remotos ou originados de outras branches) podem causar confusão e as pessoas podem perder suas modificações (tanto locais quanto remotas) por causa de divergências e conflitos.
Usado para fazer squash, editar mensagens, editar/apagar/reordenar commits, etc.
pick 002a7cc Improve description and update document title
pick 897f66d Add contributing section
pick e9549cf Add a section of Available languages
pick ec003aa Add "What is a commit" section"
pick bbe5361 Add source referencing as a point of help wanted
pick b71115e Add a section explaining the importance of commit messages
pick 669bf2b Add "Good practices" section
pick d8340d7 Add capitalization of first letter practice
pick 925f42b Add a practice to encourage good descriptions
pick be05171 Add a section showing good uses of message body
pick d115bb8 Add generic messages and column limit sections
pick 1693840 Add a section about language consistency
pick 80c5f47 Add commit message template
pick 8827962 Fix triple "m" typo
pick 9b81c72 Add "Rebase vs Merge" section
# Rebase 9e6dc75..9b81c72 onto 9e6dc75 (15 commands)
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commit's log message
# x, exec = run command (the rest of the line) using shell
# d, drop = remove commit
#
# These lines can be re-ordered; they are executed from top to bottom.
#
# If you remove a line here THAT COMMIT WILL BE LOST.
#
# However, if you remove everything, the rebase will be aborted.
#
# Note that empty commits are commented out
Útil para facilitar a limpeza sem perder tempo/trabalho com um rebase. Exemplos.
Bastante útil quando você precisa pegar aquele commit que você fez no branch errado sem precisar reescrever novamente.
Exemplo:
$ git cherry-pick 790ab21
[master 094d820] Fix English grammar in Contributing
Date: Sun Feb 25 23:14:23 2018 -0300
1 file changed, 1 insertion(+), 1 deletion(-)
Exemplo de diff:
diff --git a/README.md b/README.md
index 7b45277..6b1993c 100644
--- a/README.md
+++ b/README.md
@@ -186,10 +186,13 @@ bebebe Corrige nome de método na classe InventoryBackend
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
cdcdcd Agora vai
``
+### Template
+
+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)Podemos usar git add -p para adicionar apenas os patches que queremos, sem a necessidade de alterar o código que já está escrito.
É útil para dividir uma grande mudança em commits menores ou para fazer reset/checkout de mudanças específicas.
Stage this hunk [y,n,q,a,d,/,j,J,g,s,e,?]? s
Split into 2 hunks.
@@ -186,7 +186,6 @@
``
# Bad (mixes English and Portuguese)
ababab Usa o InventoryBackendPool para recuperar o backend de estoque
-efefef Add `use` method to Credit model
cdcdcd Agora vai
``
Stage this hunk [y,n,q,a,d,/,j,J,g,e,?]?@@ -190,6 +189,10 @@
``
cdcdcd Agora vai
``
+### Template
+
+This is a template, [written originally by Tim Pope](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html), which appears in the [_Pro Git Book_](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project).
+
## Contributing
Any kind of help would be appreciated. Example of topics that you can help me with:
Stage this hunk [y,n,q,a,d,/,K,j,J,g,e,?]?
@@ -202,3 +205,4 @@ Any kind of help would be appreciated. Example of topics that you can help me wi
- [How to Write a Git Commit Message](https://chris.beams.io/posts/git-commit/)
- [Pro Git Book - Commit guidelines](https://git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines)
+- [A Note About Git Commit Messages](https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)Todo tipo de ajuda é bem-vinda. Exemplos de tópicos em que você pode contribuir:
- Correcões gramaticais e ortográficas
- Tradução para novas línguas
- Melhoras nas referências e fontes