Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Linus: please write good git commit messages

github.com

Post reply on HN
Print view View original

41–50 of 58 posts

Re: Linus: please write good git commit messages

#41

Post by JoshTriplett »

barumrho wrote: post #30
timknauf wrote: post #12

I'm curious about this: please do proper word-wrap and keep columns shorter than about 74 characters or so How come word-wrapping is left as a task for humans here? Is there a technical/stylistic/cultural reason why lines can't be wrapped automatically to any desired width by the log presentation layer?

I hate to ask an off-topic question here, but is it considered good/bad practice to word-wrap plain text emails?

Good practice. If you don't word-wrap plain-text emails, each paragraph will show up as one long line; the program reading your mail on the other end can't wrap it automatically, because it might represent code, ASCII art, terminal transcripts, or something else that shouldn't get wrapped.

So, wrap your paragraphs in plain-text email at some sensible column. Common convention suggests 72, because that allows for a few rounds of quoting before it passes 80.

Re: Linus: please write good git commit messages

#42

Post by JoshTriplett »

telemachos wrote: post #31
barumrho wrote: post #30

Earlier quoted context omitted.

I hate to ask an off-topic question here, but is it considered good/bad practice to word-wrap plain text emails?

I think so, yes. Certainly, something like this is very common in Mutt configuration files: set editor="vim -c 'set tw=75 ft=mail noautoindent'" The 'set tw=75' bit, sets the text width to 75 columns.

Not actually necessary these days. vim knows to match the names used for mutt temporary files, and automatically puts uses mail mode and a sensible text width.

Re: Linus: please write good git commit messages

#43

Post by JoshTriplett »

adambyrtek wrote: post #38
dustingetz wrote: post #35

we use ISSUE-1234: persist client-side display configuration to settings and our issue tracking and code review software recognize issue numbers and hyperlink to the actual issue, with comments, reported-by, description, environment, replication steps, related changesets, code reviews, etc. pretty great especially considering multiple commits on the same issue which can't be rewritten into one commit because they've…

Is this usually the case that exactly one commit maps to a single issue? I'd rather expect a whole branch to cover one issue (unless it's completely trivial). In this case, repeating the same issue number in every commit message on a branch doesn't seem very useful.

For bugs, I'd expect a single commit to provide the fix; otherwise, the bug report needs splitting into multiple independent bugs. :)

Feature requests might require a whole branch, though. But in those cases, each individual commit in the branch would build towards the feature, and should reference the feature request.

Re: Linus: please write good git commit messages

#44

Post by JoshTriplett »

timknauf wrote: post #12

I'm curious about this: please do proper word-wrap and keep columns shorter than about 74 characters or so How come word-wrapping is left as a task for humans here? Is there a technical/stylistic/cultural reason why lines can't be wrapped automatically to any desired width by the log presentation layer?

Because doing so would then require extra complexity to provide a syntax for lines that should not get wrapped, such as code, transcripts, tables, ASCII art...

Hard-wrapping paragraphs to a desired length in the original log allows humans to decide which lines should wrap and which ones shouldn't, without a pile of complexity similar to HTML, Markdown, or some other markup language.

Re: Linus: please write good git commit messages

#45

Post by __david__ »

moe wrote: post #25

I try to stick to that format but very often struggle to squeeze a meaningful summary into the first line. 74 chars is just awfully short...

I have the same problem but I decided that first summary line is ok to be a little long. I regularly have my summaries be about 100 to 120 chars long. My rationale is that you aren't reading a paragraph, just a single line in isolation. For me, the hard part about reading long lines is jumping from the end of one to the beginning of the next. When the entire paragraph is on one line that problem just does not exist. Plus I always give a 1 line blank before the body of the commit so there's less visual confusion.

Re: Linus: please write good git commit messages

#46

Post by MostAwesomeDude »

prodigal_erik wrote: post #33
MostAwesomeDude wrote: post #20

Earlier quoted context omitted.

So, you've never had a commit like this one? deep/magic: Commit changes even if not dirty. Changesets are somewhat magical these days (obviously!); even if they are not dirtied; they could end up being really, *really* bogus as far as their on-disk status. The reason, as far as I can tell, is that in deep/wizardry, we are being very liberal about our modifications to the on-disk data structures without actually consi…

I would prefer to see that rationale in the comments or some implementation doc or something. In the git history it's eventually going to be troublesome to unearth, unless the change remains intact enough for "git blame" to give you a pointer to that old commit, or your whole team standardizes keywords for more searchable commit messages. And if your team does have a way to find that explanation, you then need some w…

You are implying that "the team" actually reads that section of the code, and furthermore that they will actually attempt to fix any issues found in that section rather than just go find the original author and ply him with beer to get him to fix it.

Re: Linus: please write good git commit messages

#47

Post by pyre »

JoshTriplett wrote: post #42
telemachos wrote: post #31

Earlier quoted context omitted.

I think so, yes. Certainly, something like this is very common in Mutt configuration files: set editor="vim -c 'set tw=75 ft=mail noautoindent'" The 'set tw=75' bit, sets the text width to 75 columns.

Not actually necessary these days. vim knows to match the names used for mutt temporary files, and automatically puts uses mail mode and a sensible text width.

IIRC tw=72 is set whenever you change the filetype to 'mail'

Re: Linus: please write good git commit messages

#48

Post by codex »

JoshTriplett wrote: post #44
timknauf wrote: post #12

I'm curious about this: please do proper word-wrap and keep columns shorter than about 74 characters or so How come word-wrapping is left as a task for humans here? Is there a technical/stylistic/cultural reason why lines can't be wrapped automatically to any desired width by the log presentation layer?

Because doing so would then require extra complexity to provide a syntax for lines that should not get wrapped, such as code, transcripts, tables, ASCII art... Hard-wrapping paragraphs to a desired length in the original log allows humans to decide which lines should wrap and which ones shouldn't, without a pile of complexity similar to HTML, Markdown, or some other markup language.

Couldn't our woes be solved with something as simple as soft-wrap with a tweak:

soft-wrap:

- to allow the presentation layer to soft-wrap a line, just don't add a newline.

- for new paragraphs, just add two newlines as usual

- for indent sensitive code, diagrams, etc. add newlines where appropriate, taking care to not exceed 74 columns for any line. Everyone does this already.

+ tweak:

- in the presentation layer, soft-wrap all lines except those less than 74 characters long.

This isn't perfect for terminals less than 80 characters wide, in that the diagrams won't fit, but nobody uses narrow terminals, and Linus' scheme is even more broken for this case, so it's strictly better. It also allows one to easily distinguish diagrams from non diagrams by eyeballing the text flow. Best of all, it makes fewer assumptions about terminal width.

Re: Linus: please write good git commit messages

#49

Post by JoshTriplett »

codex wrote: post #48
JoshTriplett wrote: post #44

Earlier quoted context omitted.

Because doing so would then require extra complexity to provide a syntax for lines that should not get wrapped, such as code, transcripts, tables, ASCII art... Hard-wrapping paragraphs to a desired length in the original log allows humans to decide which lines should wrap and which ones shouldn't, without a pile of complexity similar to HTML, Markdown, or some other markup language.

Couldn't our woes be solved with something as simple as soft-wrap with a tweak: soft-wrap: - to allow the presentation layer to soft-wrap a line, just don't add a newline. - for new paragraphs, just add two newlines as usual - for indent sensitive code, diagrams, etc. add newlines where appropriate, taking care to not exceed 74 columns for any line. Everyone does this already. + tweak: - in the presentation layer, so…

Text that shouldn't wrap can exceed 74 characters. Some examples: log messages, transcripts, large tables. So, no, that wouldn't suffice.

Re: Linus: please write good git commit messages

#50

Post by nodata »

timknauf wrote: post #12

I'm curious about this: please do proper word-wrap and keep columns shorter than about 74 characters or so How come word-wrapping is left as a task for humans here? Is there a technical/stylistic/cultural reason why lines can't be wrapped automatically to any desired width by the log presentation layer?

It makes the committer think longer about their commit message.
Post reply on HN