Git Commit Messages : 50/72 Formatting
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:
His blog post gives the rationale for these recommendations (which I will call "50/72 formatting" for brevity):
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. So, I have a couple of parts to my question:
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.)
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
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.
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 (ie, 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.
链接地址: http://www.djcxy.com/p/35484.html下一篇: Git提交消息：50/72格式