
Linus: please write good git commit messages - DanielRibeiro
https://github.com/torvalds/subsurface/blob/master/README#L161
======
timknauf
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?

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

~~~
telemachos
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.

~~~
JoshTriplett
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.

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

------
rmc
Am I the only one that thought this was someone asking Linus Torvalds to write
better commit messages?

~~~
mapleoin
The submission text was right, though. It would have been a comma instead of
colons if "Linus" were in the vocative case.

~~~
itmag
Et tu, Line?

------
jacknagel
It's hard to understate the importance of this.

GitHub's online editor has a default commit message along the lines of "Edited
path/to/file", and I see a lot of pull requests with that message, and nothing
else. That's about the most useless message possible, since it adds no
information that isn't already implicit in the commit. It would be better to
leave it blank and force users to at least write _something_.

~~~
tl
Be careful, we do that by default and we get a lot of "commit", "commit",
"commit $date", "merge commit" messages from some programmers. Either a
programmer accepts that a meaningful message is important on commits, or they
don't. It's a people problem not a technical one.

~~~
arkitaip
Ah, but what if we encouraged programmers to write better commit messages?
What if we splashed on a bit of gamification to raise everyone's level of
awareness? Maybe a badge on your profile page...?

~~~
drivingmenuts
How would you objectively determine the usefulness of a commit message,
though? While it might contain all the necessary parts, there is no way to
determine if the sum of the parts adds up to a useful whole.

Also, badges are done to death. Everyone's got badges these days - so much so
they're like ads. Personally, I've developed a blind spot to most of them.

~~~
arkitaip
Objectivity is irrelevant and impossible in this context of raising awareness
and fun. If the mechanism was something as simple as an upvote next to the
commit message, you would let the community define usefulness of the commit
message.

~~~
andrewflnr
Upvoting itself might be all you need.

------
secoif
Basically, your git log should read like a blog about your project.

------
zacharyvoase
Not to sound like I'm boasting, but most of my commits are far too atomic to
warrant more than a first line. If I need to write several paragraphs about
the changes I'm making, it's definitely too large a commit.

~~~
MostAwesomeDude
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 considering whether or not any
        other owner of that structure is pending changes to commit. As a result,
        we could end up heavily corrupting these structures if we're not careful.
    
        I'm not altering the comments in the file because, frankly, the comments
        imply that we should have already been doing this. I just changed the
        code to match.
    
        Fixes #4242. Finally! Time to go grab a beer. :3
    
        Tests: +5 working
    
        mad/deep/magic.py | 1 +
        1 file changed, 1 insertion(+), 0 deletions(-)

~~~
prodigal_erik
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 way for them to discover whether it has become
inaccurate over time.

~~~
rmccue
Comments about the change itself, and the rationale behind it, should go in
commit messages. Comments about the implementation itself should go in the
code. Granted, there is some overlap between the two, in which case, go with
code only (since it's part of the commit anyway).

------
rbxbx
<http://stopwritingramblingcommitmessages.com/>

------
adambyrtek
This is a good post about readable commit messages:

[http://tbaggery.com/2008/04/19/a-note-about-git-commit-
messa...](http://tbaggery.com/2008/04/19/a-note-about-git-commit-
messages.html)

------
moe
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...

~~~
__david__
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.

------
dustingetz
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 already been pushed. it also makes
`git log --oneline` useful.

~~~
adambyrtek
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.

~~~
JoshTriplett
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.

~~~
adambyrtek
From my experience, a bug can be simple to describe and atomic, but still
require a significant amount of work to fix. I'm all for linking to bugs and
feature requests in commit descriptions, but I wouldn't make it a hard
requirement and put on the first line. Your mileage may vary.

------
melloclello
I'm terrible. I'll edit things randomly then make commits _before_ I'm about
to do something.

~~~
danssig
This is one of the great things git makes it easier to do.

------
billpatrianakos
At first I thought someone was asking Linus to do this.

But this comes up over and over and people should really start doing it!
Especially on large and/or well known projects. This isn't just something
that's useful to others but it can help you too! I'm a naturally long-winded
person but the point isn't to write an essay, you just have to sum it up on
line 1 give some context and details for the commit, then let us know who you
are and how to get in touch.

Fortunately I've never had to revert Amy changes in my work (weird, right?)
but if and when that day comes I'll be prepared. 99% of my work is done alone
but I still write some decent commit messages. Who here remembers the date of
your changes? Do you remember the exact state of the project at that time?
Even if you remember that "well, the project was in X state Y commits ago"
it'll only help you for about 5 commits max then you'll forget.

You need to know what you were doing and so do others. Even if you don't plan
on working with others, I'd you're on GitHub with a public repo someone may
unexpectedly like your project and want to see what's up with each commit. I
recently had a project up on github that I thought was literally only useful
for myself. It was a basic brochure style website for someone I made as a
favor. Well it turns out someone here on HN wanted to learn to code, got in
touch with me privately, then started exploring my github repos nth at guy
actually used the stupid website I was building as a way to look at some code,
tear it apart, and see how it worked. I was flattered and now I'm glad I write
decent commit messages even if I'm only working with myself.

The point is, you'll never know when someone else or even yourself will need
to look back at the logs and if the commit message is nothing but a date or
something like "fixed the link" then you aren't reverting to a known past
state - you're guessing.

I know a lot of Git newbies get scared after pressing return in the command
line and nano or whatever built in text editor pops up. I didn't know how to
end the commit message the first few times and save it or get back to the
"normal" terminal so this may be part of why this happens but not a big part.

In any case, I feel strongly that this is an important thing that's overlooked
and I'm glad it was brought up again. Hopefully people do it.

