Git Commit-Nachrichten: 50/72 Formatierung

Tim Pope spricht sich in seinem Blog-Beitrag für einen bestimmten Git-Commit-Nachrichtenstil aus: http://www.tpope.net/node/106 .

Hier ist eine kurze Zusammenfassung dessen, was er empfiehlt:

• Die erste Zeile besteht aus maximal 50 Zeichen.
• Dann eine leere Zeile.
• Der verbleibende Text sollte mit 72 Zeichen umbrochen werden.

Sein Blog-Beitrag gibt die Gründe für diese Empfehlungen (die ich der Kürze halber als "50/72-Formatierung" bezeichnen werde):

• In der Praxis behandeln einige Tools die erste Zeile als Betreffzeile und den zweiten Absatz als Text (ähnlich wie bei E-Mails).
• git log behandelt das Umbrechen nicht, daher ist es schwer zu lesen, wenn die Zeilen zu lang sind.
• git format-patch --stdout Konvertiert Commits in E-Mails. Um gut zu spielen, ist es hilfreich, wenn Ihre Commits bereits gut verpackt sind.

Ein Punkt, den ich hinzufügen möchte, dem Tim meiner Meinung nach zustimmen würde:

• Das Zusammenfassen Ihres Commits ist eine bewährte Methode in jedem Versionskontrollsystem. Es hilft anderen (oder Ihnen später), relevante Commits schneller zu finden.

Ich habe also ein paar Blickwinkel auf meine Frage:

• Welcher Teil (ungefähr) der "Vordenker" oder "erfahrenen Benutzer" von Git befürwortet den Formatierungsstil 50/72? Ich frage dies, weil neuere Benutzer manchmal die Community-Praktiken nicht kennen oder sich nicht darum kümmern.
• Gibt es für diejenigen, die diese Formatierung nicht verwenden, einen grundsätzlichen Grund für die Verwendung eines anderen Formatierungsstils? (Bitte beachten Sie, dass ich nach einem Argument in der Sache suche, nicht nach "Ich habe noch nie davon gehört" oder "Es ist mir egal".)
• Wie viel Prozent der Git-Repositories unterstützen diesen Stil empirisch? (Falls jemand eine Analyse der GitHub-Repositorys durchführen möchte ... Hinweis, Hinweis.)

Mein Punkt hier ist nicht, den 50/72-Stil zu empfehlen oder andere Stile abzuschießen. (Um offen darüber zu sein, bevorzuge ich es, aber ich bin offen für andere Ideen.) Ich möchte nur die Gründe dafür herausfinden, warum Leute verschiedene Git-Commit-Nachrichtenstile mögen oder ablehnen. (Sie können auch Punkte ansprechen, die noch nicht erwähnt wurden.)

In Bezug auf die Zeile "Zusammenfassung" (die 50 in Ihrer Formel) enthält die Linux-Kerneldokumentation Folgendes :

For these reasons, the "summary" must be no more than 70-75
characters, and it must describe both what the patch changes, as well
as why the patch might be necessary.  It is challenging to be both
succinct and descriptive, but that is what a well-written summary
should do.

Das heißt, es scheint, als würden Kernel-Betreuer tatsächlich versuchen, die Dinge um die 50 zu halten. Hier ist ein Histogramm der Länge der Zusammenfassungszeilen im Git-Protokoll für den Kernel:

( Ansicht in voller Größe )

Es gibt ein paar Commits mit Zusammenfassungszeilen, die länger (einige viel länger) sind, als diese Darstellung enthalten kann, ohne dass der interessante Teil wie eine einzelne Zeile aussieht. (Es gibt wahrscheinlich eine ausgefallene statistische Technik, um diese Daten hier aufzunehmen, aber na ja… :-)

Wenn Sie die Rohlängen sehen möchten:

cd /path/to/repo
git shortlog  | grep -e '^      ' | sed 's/[[:space:]]\+\(.*\)$/\1/' | awk '{print length($0)}'

oder ein textbasiertes Histogramm:

cd /path/to/repo
git shortlog  | grep -e '^      ' | sed 's/[[:space:]]\+\(.*\)$/\1/' | awk '{lens[length($0)]++;} END {for (len in lens) print len, lens[len] }' | sort -n

In Bezug auf „Vordenker“: Linus befürwortet nachdrücklich das Zeilenumbruch für die vollständige Commit-Nachricht:

[…] Wir verwenden Spalten mit 72 Zeichen für den Zeilenumbruch, mit Ausnahme von zitiertem Material mit einem bestimmten Zeilenformat.

Die Ausnahmen beziehen sich hauptsächlich auf "Nicht-Prosa" -Text, dh Text, der nicht von einem Menschen für das Commit eingegeben wurde - beispielsweise Compiler-Fehlermeldungen.

Die Trennung von Präsentation und Daten bestimmt meine Commit-Nachrichten hier.

Ihre Festschreibungsnachricht sollte bei keiner Zeichenanzahl fest umbrochen werden. Stattdessen sollten Zeilenumbrüche verwendet werden, um Gedanken, Absätze usw. als Teil der Daten und nicht der Präsentation zu trennen. In diesem Fall sind die "Daten" die Nachricht, die Sie vermitteln möchten, und die "Präsentation" ist, wie der Benutzer dies sieht.

Ich verwende oben eine einzelne Zusammenfassungszeile und versuche, sie kurz zu halten, beschränke mich aber nicht auf eine beliebige Zahl. Es wäre weitaus besser, wenn Git tatsächlich eine Möglichkeit bieten würde, Zusammenfassungsnachrichten als separate Entität von der Nachricht zu speichern, aber da dies nicht der Fall ist, muss ich eine einhacken und verwende den ersten Zeilenumbruch als Trennzeichen (zum Glück unterstützen viele Tools dies bedeutet, die Daten auseinanderzubrechen).

Für die Nachricht selbst weisen Zeilenumbrüche auf etwas Bedeutendes in den Daten hin. Eine einzelne neue Zeile zeigt einen Start / Bruch in einer Liste an und eine doppelte neue Zeile zeigt einen neuen Gedanken / eine neue Idee an.

This is a summary line, try to keep it short and end with a line break.
This is a thought, perhaps an explanation of what I have done in human readable format.  It may be complex and long consisting of several sentences that describe my work in essay format.  It is not up to me to decide now (at author time) how the user is going to consume this data.

Two line breaks separate these two thoughts.  The user may be reading this on a phone or a wide screen monitor.  Have you ever tried to read 72 character wrapped text on a device that only displays 60 characters across?  It is a truly painful experience.  Also, the opening sentence of this paragraph (assuming essay style format) should be an intro into the paragraph so if a tool chooses it may want to not auto-wrap and let you just see the start of each paragraph.  Again, it is up to the presentation tool not me (a random author at some point in history) to try to force my particular formatting down everyone else's throat.

Just as an example, here is a list of points:
* Point 1.
* Point 2.
* Point 3.

So sieht es in einem Viewer aus, der den Text weich umschließt.

Dies ist eine zusammenfassende Zeile. Versuchen Sie, sie kurz zu halten und mit einem Zeilenumbruch zu beenden.

Dies ist ein Gedanke, vielleicht eine Erklärung dessen, was ich in einem für Menschen lesbaren Format getan habe. Es kann komplex und lang sein und aus mehreren Sätzen bestehen, die meine Arbeit im Essay-Format beschreiben. Es liegt nicht an mir, jetzt (zum Zeitpunkt des Autors) zu entscheiden, wie der Benutzer diese Daten verwenden wird.

Zwei Zeilenumbrüche trennen diese beiden Gedanken. Der Benutzer liest dies möglicherweise auf einem Telefon oder einem Breitbildmonitor. Haben Sie jemals versucht, Text mit 72 Zeichen auf einem Gerät zu lesen, auf dem nur 60 Zeichen angezeigt werden? Es ist eine wirklich schmerzhafte Erfahrung. Außerdem sollte der Anfangssatz dieses Absatzes (unter der Annahme eines Aufsatzformats) eine Einführung in den Absatz sein. Wenn ein Werkzeug dies wählt, möchte es möglicherweise nicht automatisch umbrochen werden, sodass Sie nur den Anfang jedes Absatzes sehen können. Auch hier ist es Sache des Präsentationstools, nicht ich (irgendwann in der Geschichte ein zufälliger Autor), zu versuchen, meine spezielle Formatierung in die Kehle aller anderen zu zwingen.

Als Beispiel hier eine Liste von Punkten:
* Punkt 1.
* Punkt 2.
* Punkt 3.

Mein Verdacht ist, dass der Autor der von Ihnen verlinkten Git-Commit-Nachrichtenempfehlung noch nie zuvor Software geschrieben hat, die von einer Vielzahl von Endbenutzern auf verschiedenen Geräten (dh einer Website) verwendet wird, seit zu diesem Zeitpunkt in der Entwicklung von Software / Computing Es ist bekannt, dass das Speichern Ihrer Daten mit fest codierten Präsentationsinformationen eine schlechte Idee ist, was die Benutzererfahrung betrifft.

Ich würde zustimmen, dass es interessant ist, einen bestimmten Arbeitsstil vorzuschlagen. Sofern ich nicht die Möglichkeit habe, den Stil festzulegen, folge ich normalerweise dem, was aus Gründen der Konsistenz getan wurde.

Werfen Sie einen Blick auf die Linux Kernel Commits, das Projekt, mit dem git gestartet wurde, wenn Sie möchten: http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h = bca476139d2ded86be146dae09b06e22548b67f3 , sie folgen nicht der 50/72-Regel. Die erste Zeile besteht aus 54 Zeichen.

Ich würde sagen, Konsistenz ist wichtig. Richten Sie geeignete Methoden zur Identifizierung von Benutzern ein, die Commits vorgenommen haben (user.name, user.email - insbesondere in internen Netzwerken. User @ OFFICE-1-PC-10293982811111 ist keine nützliche Kontaktadresse). Stellen Sie je nach Projekt die entsprechenden Details im Commit zur Verfügung. Es ist schwer zu sagen, was das sein soll; Es können Aufgaben sein, die in einem Entwicklungsprozess erledigt wurden, und dann Details darüber, was geändert wurde.

Ich glaube nicht, dass Benutzer Git in eine Richtung verwenden sollten, da bestimmte Schnittstellen zum Git die Commits auf bestimmte Weise behandeln.

Ich sollte auch beachten, dass es andere Möglichkeiten gibt, Commits zu finden. Zunächst git differfahren Sie, was sich geändert hat. Sie können auch git log --pretty=format:'%T %cN %ce'die Optionen von formatieren git log.

Ist die maximal empfohlene Titellänge wirklich 50?

Ich habe das jahrelang geglaubt, aber wie ich gerade bemerkt habe, heißt es in der Dokumentation von "git commit" tatsächlich

$ git help commit | grep -C 1 50
      Though not required, it’s a good idea to begin the commit message with
      a single short (less than 50 character) line summarizing the change,
      followed by a blank line and then a more thorough description. The text

$  git version
git version 2.11.0

Man könnte argumentieren, dass "weniger als 50" nur "nicht länger als 49" bedeuten kann.