Ein Leitfaden um die Wichtigkeit von Commit-Messages zu verstehen und diese richtig zu formulieren.
Verstehe was ein Commit ist, warum es wichtig ist eine gute Commit-Message zu schreiben, Best-Practices und ein paar Tipps um eine saubere Commit-Historie zu planen oder vielleicht sogar nachträglich noch anzupassen.
Auch wenn das eine Übersetzung darstellen soll, empfiehlt es sich, alle Commit-Messages auf Englisch zu schreiben, deshalb sind die Beispiele nicht übersetzt.
Ganz einfach beschrieben ist ein Commit eine Art Schnappschuss deiner lokalen Dateien in deinem Repository (dein Projektordner). Im Gegensatz zur geläufigen Annahme speichert Git nicht nur die Unterschiede in den Dateien sonder immer die gesamte Datei (Quelle auf Englisch). Für Dateien die sich von einem auf den anderen Commit nicht geändert haben, speichert Git lediglich einen Link zur einer bereits gespeicherten Version in einem vorangegangenen Commit.
Die folgende Grafik zeigt wie Git die Daten mit der Zeit speichert. Jede "Version" meint hier einen Commit.
- Um Code-Reviews zu beschleunigen und zu vereinfachen
- Um die erzielte Änderung besser verstehen zu können
- Um die Gründe zu erläutern die so nicht aus dem Code hervorgehen (Grundsatzentscheidungen)
- um zukünfitigen Entwicklern zu helfen zu verstehen wie und warum Änderungen gemacht wurden – was die Fehlersuche und -behebung vereinfacht
Um diese und noch mehr Vorteile möglichst effizient nutzen zu können, sollten wir uns an die folgenden Praktiken und Stardards halten.
Dies sind Praktiken aus meiner eigenen Erfahrung sowie aus anderen Artikeln/Guides aus dem Internet. Wenn du noch mehr Tipps hast oder manche dieser Praktiken für nicht sinnvoll hältst beantrage gerne eine Änderung via Pull Request.
# Good
Use InventoryBackendPool to retrieve inventory backend
# Bad
Used InventoryBackendPool to retrieve inventory backend
Warum soll ich den Imperativ benutzen?
Eine Commit-Message beschreibt was die Änderung tatsächlich tut – ihre Auswirkungen – nicht was vorher war.
Dieser sehr gute Artikel von Chris Beams (Quelle auf Englisch) gibt uns einen simplen Satzbau vor, dieser hilft dabei bessere Commit-Messages im imperativ zu schreiben:
If applied, this commit will: <commit message>
Beispiel:
# 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
Diese Regelung macht grammatikalisch schlichtweg Sinn, da man den grammatikalischen Regeln bzgl. Großbuchstaben am Satzanfang gerecht wird.
Diese Regelung kann von Entwickler zu Entwickler, Team zu Team oder auch Sprache zu Sprache unterschiedlich sein.
Großschreiben oder nicht, wichtig ist nur, dass man bei einer Variante bleibt.
# Good
Add `use` method to Credit model
# Bad
Add `use` method
# Good
Increase left padding between textbox and layout frame
# Bad
Adjust css
Dies ist in vielen Situationen (z.B.: mehrer kleine Commits, Refactoring) sinnvoll um besser zu verstehen, was sich der Entwickler gedacht hat.
# 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 model
Change from namedtuple to class because we need to
setup a new attribute (in_use_amount) with a new value
Titel bzw. Betreff der Commit-Message und die Beschreibung müssen mit einer Leerzeile getrennt werden. Alle weiteren Leerzeilen oder Absätze werden als Teil der Beschreibung gewertet.
Trenn- oder Aufzählungszeichen, wie z.B.: -, * oder \ verbessern die Lesbarkeit der Beschreibung.
# Bad
Fix this
Fix stuff
It should work now
Change stuff
Adjust css
Es wird empfohlen (Quelle in ENG) maximal 50 Zeichen für den Titel/Betreff und 72 Zeichen für die Nachricht zu verwenden.
Dies gilt vor allem für Entwickler für die Englisch nicht die Muttersprache ist. Logischerweise sollte man sich immer dem etablierten Standard anpassen – ganz besonders bei Repositories mit Entwicklern aus vielen verschiedenen Ländern.
Entscheide dich für eine Sprache und bleibe dabei.
# Good
ababab Add `use` method to Credit model
efefef Use InventoryBackendPool to retrieve inventory backend
bebebe Fix method name of InventoryBackend child classes
# Good (German example)
ababab Fügt die `use` Funktion dem Credit Model hinzu
efefef Nutzt den InventoryBackendPool um aufs Bestands-BackEnd zuzugreifen
bebebe Korrigiert den Methodennamen der InventoryBackend Kind-Klassen
# Bad (mixes English and German)
ababab Fügt die `use` Funktion dem Credit Model hinzu
efefef Add `use` method to Credit model
cdcdcd Fix method name of InventoryBackend child classes
Das folgende Template, im Original von Tim Pope (Quelle auf Englisch), erschienen so auch in dem Buch Pro Git Book (Quelle auf Englisch).
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
Dieser Abschnitt ist ein Tl;DR des lesenswerten Artikels Atlassian's article Merging vs. Rebasing (Quelle auf Englisch).
TL;DR: Wendet die Änderungen des aktuellen Branches auf den Stand des Basis-Branches an.
TL;DR: Erstellt einen neuen Commit, auch Merge-Commit, dieser führt die Änderungen beider Branches zusammen.
Ich persönlich bevorzuge rebase. Gründe dafür sind unter anderem:
-
Es entsteht eine "saubere" Historie, ohne unnötige Merge-Commits.
-
What you see is what you get, z.B.: in eine Code-Review sieht man wirklich jeden Commit. Es sind keine Änderungen in Merge-Commits versteckt.
-
Jedes Zusammenführen von Code geschiet einzeln durch den Entwickler, so hat jeder Merge einen eigenen Commit mit einer entsprechenen Commit-Message.
- Im Normalfall werden Merge-Commits in einer Code-Review nicht betrachtet. Hat jede Änderung/Zusammenführung einen eigenen Commit, kann man sicher sein, dass alles an der richtigen Stelle ist und betrachtet werden kann.
Squash beschreibt eine Methode in der eine Reihe von Commits in einen einzelnen Commit zusammengefasst werden.
Hilfreich bei z.B.:
- dem Reduzieren von kleinen/kontextlosen Commits (Rechtschreibfehler, Formatierung, vergessene Änderungen)
- dem Zusammenführen mehrere Commits die als Ganzes mehr Sinn ergeben
- dem Neu-Verpacken von work in progress Commits
Vermeiden Sie die Verwendung von Rebase und Squash in öffentlichen Commits oder in Branches, in denen mehrere Personen arbeiten.
Rebase und Squash verändern die Historie der Commits und überschreiben bestehende Commits. Verwendet man rebase und squash auf Commits, die sich auf einen gemeinsam genutzten Branch befinden (d.h. Commits, die in ein Remote Repository verschoben wurden oder von anderen Branches stammen), erzeugt man unötige Verwirrung. Darüber hinaus besteht die Gefahr, dass Andere ihre Änderungen (sowohl lokal als auch auf dem Remote) verlieren, aufgrund von unterschiedlichen Trees und anderen Konflikten.
Wird verwenet um Commits zu squashen, Commit-Messages zu bearbeiten, Neuschreiben/Löschen/Neuordnen von Commits, usw.
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
Wird verwendet um Commits einfach anzupassen ohne einen komplexen Rebase durchzuführen. Dieser Artikel (Quelle auf Englisch) beschreibt mit Beispielen wie und wann man einen fixup durchführt.
Sehr hilfreich wenn man einen Commit der z.B.: versehentlich im falschen Branch gepusht wurde auf den richtigen Branch anwenden will ohne diesen neuschreiben zu müssen.
Beispiel:
$ 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(-)
Angenommen wir haben die folgenden offenen Änderungen:
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 [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)Mit git add -p können wir nun ausschließlich die gewünschten Abschnitte zum Commit hinzufügen, ganz ohne dass wir bestehenden Code ändern müssen. Das ist hilfreich um größere Änderungen in mehrere kleine Commits aufzuteilen oder um ungewollte Änderungen gezielt rückgängig zu machen.
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 [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)Jede Art von Hilfe ist willkommen. Zum Beispiel zu den Themen:
- Grammatik und Rechtschreibung
- Übersetzung in andere Sprachen
- Verbesserung der Quell-Referenzen
- Falsche oder unvollständige Information