Git Commit Messages: 50/72 Formatting

Question

Tim Pope argues for a particular Git commit message style in his blog post: http://www.tpope.net/node/106.

Here is a quick summary of what he recommends:

• First line is 50 characters or less.
• Then a blank line.
• Remaining text should be wrapped at 72 characters.

His blog post gives the rationale for these recommendations (which I will call “50/72 formatting” for brevity):

• In practice, some tools treat the first line as a subject line and the second paragraph as a body (similar to email).
• git log does not handle wrapping, so it is hard to read if lines are too long.
• git format-patch --stdout converts commits to email — so to play nice it helps if your commits are already wrapped nicely.

A point I would like to add that I think Tim would agree with:

• The act of summarizing your commit is a good practice inherently in any version control system. It helps others (or a later you) find relevant commits more quickly.

So, I have a couple of angles to my question:

• What chunk (roughly) of the “thought leaders” or “experienced users” of Git embrace the 50/72 formatting style? I ask this because sometime newer users don’t know or don’t care about community practices.
• For those that don’t use this formatting, is there a principled reason for using a different formatting style? (Please note that I’m looking for an argument on the merits, not “I’ve never heard of it” or “I don’t care.”)
• Empirically speaking, what percentage of Git repositories embrace this style? (In case someone wants to do an analysis on GitHub repositories… hint, hint.)

My point here is not to recommend the 50/72 style or shoot down other styles. (To be open about it, I do prefer it, but I am open to other ideas.) I just want to get the rationale for why people like or oppose various Git commit message styles. (Feel free to bring up points that haven’t been mentioned, too.)

Sofa

I just noticed that Github's web interface will warn you if your first line is longer than 50 characters by saying "ProTip: Great commit summaries are 50 characters or less. Place extra information in the extended description." – Sofa

There's a good summary of the 50/72 reasoning in this answer, including some historical reasoning: https://mcmap.net/q/87540/-keep-commit-message-subject-under-50-characters-in-sourcetree – Araucaria

Answer 1

Regarding the “summary” line (the 50 in your formula), the Linux kernel documentation has this to say:

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.

That said, it seems like kernel maintainers do indeed try to keep things around 50. Here’s a histogram of the lengths of the summary lines in the git log for the kernel:

(view full-sized)

There is a smattering of commits that have summary lines that are longer (some much longer) than this plot can hold without making the interesting part look like one single line. (There’s probably some fancy statistical technique for incorporating that data here but oh well… :-)

If you want to see the raw lengths:

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

or a text-based histogram:

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

Simard

How did you generate your histogram, out of curiosity? – Azide

matplotlib in python. Something like this but with the output from one of the commands in my answer instead of the random data. – Simard

Using GNU AWK: git shortlog | awk '/^ / {gensub(/[[:space:]]\+\(.*\)$/, "\\1", ""); print length()}' – Fayola

So is the 50 just an arbitrary guide to encourage brevity but the 72 a rule to meet a technical consideration for fitting with git output? – Gipps

Github will hide commit message text after the 70th character. – Epiphenomenon

(@Dennis) In any POSIX awk '{sub(/^[[:space:]]+/,"");print length}' and for the histogram version in recent gawk you can use PROC_INFO["sorted_in"]="@ind_num_asc" and skip the sort -n but I wouldn't bother. – Syndesis

Using sort -n should be replaced with sort -g to perform a numeric sort, and get a more consistent result. – Fifine

concerning the "fancy statistical technique", you could simple make the last bin e.g. "≥ 100" – Vandenberg

The link to the file is broken. The file has been moved to this location instead. – Sorb

Isn't it fascinating that such logical, mathematical people as the Linux kernel maintainers can write a phrase like "no more than 70-75 characters"? – Payson

Answer 2

Regarding “thought leaders”: Linus emphatically advocates line wrapping for the full commit message:

[…] we use 72-character columns for word-wrapping, except for quoted material that has a specific line format.

The exceptions refers mainly to “non-prose” text, that is, text that was not typed by a human for the commit — for example, compiler error messages.

Moorhead

+1 for bringing up difference between "prose" and "non-prose". And "except for quoted material that has a specific line format". Excellent rule of thumb. – Celaeno

Answer 3

Separation of presentation and data drives my commit messages here.

Your commit message should not be hard-wrapped at any character count and instead line breaks should be used to separate thoughts, paragraphs, etc. as part of the data, not the presentation. In this case, the "data" is the message you are trying to get across and the "presentation" is how the user sees that.

I use a single summary line at the top and I try to keep it short but I don't limit myself to an arbitrary number. It would be far better if Git actually provided a way to store summary messages as a separate entity from the message but since it doesn't I have to hack one in and I use the first line break as the delimiter (luckily, many tools support this means of breaking apart the data).

For the message itself newlines indicate something meaningful in the data. A single newline indicates a start/break in a list and a double newline indicates a new thought/idea.

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.

Here's what it looks like in a viewer that soft wraps the text.

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.

My suspicion is that the author of Git commit message recommendation you linked has never written software that will be consumed by a wide array of end-users on different devices before (i.e., a website) since at this point in the evolution of software/computing it is well known that storing your data with hard-coded presentation information is a bad idea as far as user experience goes.

Kohlrabi

Wow, that commit message is painful to read even on a webpage like SO. I don't need responsive commit messages, but something which works well with tig, git log or gitk, and maybe also github. – Eruption

The message would be easy to read with any viewer that word wraps. I put it in a non-wrapping code block as an example. – Kohlrabi

Thanks for a different perspective. In theory, your answer sounds fine. In practice, I like line breaks for current command line tools. – Sofa

"storing your data with hard-coded presentation information" OK but git messages are not data but meta-data. Also, if "line break after 70 chars" is presentation information, then "two line breaks after thought" or bullet points is what? – Celaeno

The character sequence \n\n is a thought separator. \n* is a list item indicator. How those are rendered is up to the view. The problem with artificial line breaks is that they are associated with nothing except the presentation. There isn't any data-related information being transmitted by putting a line break at 70 characters. My choice of \n\n and \n* is the same as why markdown chose it, because it is a form of encoding data that also happens to look somewhat reasonable in a plain text view. – Kohlrabi

"The message would be easy to read with any viewer that word wraps." And difficult to read on a viewer that doesn't. Since some popular viewers (e.g. gitk) don't word-wrap, we'll have to do it ourselves. – Overlord

Hard wraps are difficult to read on devices with small screens (mobile). The message will be difficult to read somewhere no matter what you do. I would rather follow modern best practices than cater to legacy software that doesn't have some of the most basic rendering capabilities. – Kohlrabi

This would contradict the good email netiquette of wrapping anything longer than 80 chars. It is that which probably formed the base of the git format suggestion. Yes other devices could display more characters, but anything that fancy could take a guess at unwrapping if the user wanted. Also some devices might have smaller displays but only few cannot manage 80 chars. The intended audience was a terminal email client, not a mobile browser. You have made some interesting points though and I have long wondered when the 80 char thing could be modernised to a larger value. – Gipps

"It is up to the presentation tool… not me…" Modern presentation tools, properly written, take into account historical formatting nuances like width constraints, and remove unpaired newlines before re-wrap/display. (Markdown is a great example.) Thus, including breaks at 72 does no harm to such tools, and it has the added benefit of working nicely with less "blessed" toolchains. I understand the desire to ditch practices pushed by old tools, but in my estimation it isn't that much extra effort, and it will result in fewer people cursing you behind your back when they're stuck using less. :P – Ilium

I used to do the "hard character count" max, but now I am starting to move away from it. I have started to follow the Asciidoc recommended practice of "One Sentence Per Line". – Mansoor

For anybody who uses git gui, you can enable word wrap in its commit area by editing /usr/lib/git-core/git-gui and changing -wrap none to -wrap word in the text $ui_comm ... definition. – Darceydarci

@Gipps "anything that fancy could take a guess at unwrapping" I have yet to find an editor (embedded or standalone) that does unwrapping, even when the editor wraps itself. – Rommel

A long subject line will be unreadable in email clients. Are they legacy software too now? – Isobelisocheim

I truly, deeply, strongly disagree with this suggestion! And it's also contradictory. By one hand, the char sequences like \n\n and \n* are defended for being "markdown-like" while line length is ignored. Well, markdown considers a block of text as a virtual single line that is rendered responsively according to the view-port, while keeping the readability of the plain text version. Also, this approach is not practical. The terminal is literally where these messages are going to be read most of the times. Ignoring this obvious reality is a good way to annoy everyone working with you. – Magenmagena

I haven't looked at a git commit message in a terminal for years, I am always viewing them in more advanced tooling. Even within terminal applications, soft wrapping is widely supported these days. While I acknowledge there are still some pieces of legacy software out there in use that don't support soft-wraps, I would argue that we should not constrain ourselves because people refuse to upgrade their software. – Kohlrabi

@Isobelisocheim Sorry, just noticed your message (from years ago!) As I mentioned, I try to keep the subject line short but I don't cut it off without finishing the thought. Sometimes the thought is longer than will fit in the subject line of an email on my phone (most thoughts don't fit in that space) and that is OK. On my phone (a modern and large device) I don't believe I can see a 50 character subject line in an email notification, so the 50 character limit isn't likely to help any more in this situation. – Kohlrabi

What about separation between the summary and the first thought? This is recommended by the documentation for git commit, and is relevant in places like git log --oneline. – Loculus

To clarify, the documentation recommends using a blank line to separate the summary and description (along with short summaries, this is its only recommendation). git log, other git commands, and some UIs treat the series of non-blank lines as the summary, though other UIs (e.g. GitHub) do not. – Loculus

Since writing this, my personal style has shifted to a blank line between summary and first thought. I find it reads a bit cleaner that way when printed unformatted. – Kohlrabi

I would upvote this several times if I could. Preformatting for a specific historic line length is bad. – Charcuterie

@MarkG. "Modern presentation tools, properly written, ... remove unpaired newlines before re-wrap/display. (Markdown is a great example.)" Unfortunately GitHub doesn't do that, so when I wrap commit messages and open a PR, I have to manually remove new line characters to get it to wrap normally. – Ayakoayala

"I haven't looked at a git commit message in a terminal for years, I am always viewing them in more advanced tooling." I'm different. More often than not I'm working on the CLI or ssh'ing into a build/test/CI server, and I need to look at logs that way. Faster via git log than sftp'ing things or invoking a local GUI tool. I only use advance tooling for more complicated things (a 3-way-merge or comparing logs among branches.) – Zante

this so much. word wrapping a paragraph is a presentation issue. we shouldn't be baking our assumptions about the way the message will be displayed into the message. – Drawl

says doesn't want to "force formatting down anyone's throat" while forcing long lines down everyone's throat. It's the same as atheists pretending they're different from anyone else as if they haven't got their own set of origins beliefs. – Araucaria

I always use a terminal for my work with Git and other tools. I don't know why people who don't use terminals think they're using "more advanced" tools. They're usually the opposite: dumbed down versions with point and click alternatives to the powerful terminal scripting environment. I don't have problems with long lines in the terminal. I'm usually the one pushing for longer line lengths in the code. I don't have problems with 50/72 either and usually conform, although I'm sometimes over 50 on the first line by a few characters because sometimes that's too hard. – Araucaria

Answer 4

Is the maximum recommended title length really 50?

I have believed this for years, but as I just noticed the documentation of "git commit" actually states

$ 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

One could argue that "less then 50" can only mean "no longer than 49".

Amalita

On the other hand, the default highlighting highlights the first 50 characters. This appears to be an indeliberate discrepancy. – Jessejessee

"indeliberate discrepancy" :-D – Araucaria

@AugustJanse No more "indeliberate discrepancy"; see my answer: "no more than 50 characters". – Perpetua

Answer 5

I'd agree it is interesting to propose a particular style of working. However, unless I have the chance to set the style, I usually follow what's been done for consistency.

Taking a look at the Linux Kernel Commits, the project that started git if you like, http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=commit;h=bca476139d2ded86be146dae09b06e22548b67f3, they don't follow the 50/72 rule. The first line is 54 characters.

I would say consistency matters. Set up proper means of identifying users who've made commits (user.name, user.email - especially on internal networks. User@OFFICE-1-PC-10293982811111 isn't a useful contact address). Depending on the project, make the appropriate detail available in the commit. It's hard to say what that should be; it might be tasks completed in a development process, then details of what's changed.

I don't believe users should use git one way because certain interfaces to git treat the commits in certain ways.

I should also note there are other ways to find commits. For a start, git diff will tell you what's changed. You can also do things like git log --pretty=format:'%T %cN %ce' to format the options of git log.

Colocynth

For reference he says "As the example indicates, you should shoot for about 50 characters (though this isn’t a hard maximum)", but I suppose you have a point in that you shouldn't have to work around your tools. – Romanticist

Answer 6

One could argue that "less then 50" can only mean "no longer than 49".

Regarding Guenther Brunthaler's answer, Git 2.43 (Q4 2023) clarifies the "50 characters" limit.

See commit c2c349a (28 Sep 2023) by 谢致邦 (XIE Zhibang) (Red54).
^{(Merged by Junio C Hamano -- gitster -- in commit ba7d57b, 04 Oct 2023)}

doc: correct the 50 characters soft limit

^{Signed-off-by: 谢致邦 (XIE Zhibang)}

The soft limit of the first line of the commit message should be "no more than 50 characters" or "50 characters or less", but not "less than 50 character".

git commit now includes in its man page:

with a single short (no more than 50 characters) line summarizing the change

---

Actually, Git 2.43 (Q4 2023) adds a precision, with commit 1627e6b (08 Oct 2023) by 谢致邦 (XIE Zhibang) (Red54).
^{(Merged by Junio C Hamano -- gitster -- in commit 0bc6bff, 18 Oct 2023)}

doc: correct the 50 characters soft limit (+)

^{Signed-off-by: 谢致邦 (XIE Zhibang)}

The soft limit of the first line of the commit message should be "no more than 50 characters" or "50 characters or less", but not "less than 50 character".

This is an addition to commit c2c349a ("doc: correct the 50 characters soft limit", 2023-09-28, Git v2.43.0 -- merge listed in batch #15).

gittutorial now includes in its man page:

begin the commit message with a single short (no more than 50 characters) line summarizing the change, followed by a blank line and then a more thorough description. The text up to the first blank line in a commit message is treated as the commit title, and that title is used

user-manual now includes in its man page:

with a single short (no more than 50 characters) line summarizing the change

Perpetua