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

What a good commit message looks like (2011)

github.com

Post reply on HN
Print view View original

21–30 of 100 posts

Re: What a good commit message looks like (2011)

#21

Post by nailer »

mojuba wrote: post #14

Should be noted, it is often tempting to describe everything about the change in the commit description rather than comments in the code. Remember, git commits disappear from sight pretty soon and become fossils, whereas there may be something important that should be said in the code itself.

Also: avoid using comments where proper names would suffice:

  // cleans responses
  function zrgfy(response){
    ...
  }
should be something like:

  function cleanResponse(response){
    ...
  }

Re: What a good commit message looks like (2011)

#22

Post by superzadeh »

gempir wrote: post #18

Great system about our commit system at work is that every commit starts with the name of a ticket of our ticket system (jira) so you can go back to that ticket whenever that commit comes up anywhere and understand the commit better

even better systems allows to link tickets to commits.

Re: What a good commit message looks like (2011)

#23

Post by nevon »

mojuba wrote: post #14

Should be noted, it is often tempting to describe everything about the change in the commit description rather than comments in the code. Remember, git commits disappear from sight pretty soon and become fossils, whereas there may be something important that should be said in the code itself.

Highly disagree. As long as the code lives, the commit lives.

Re: What a good commit message looks like (2011)

#24

Post by wruza »

Just for those who are tired of sites that disable both 2tap-zoom and 'pre' block wrapping on mobile.

---

A good commit message looks like this:

Header line: explaining the commit in one line

Body of commit message is a few lines of text, explaining things in more detail, possibly giving some background about the issue being fixed, etc etc.

The body of the commit message can be several paragraphs, and please do proper word-wrap and keep columns shorter than about 74 characters or so. That way "git log" will show things nicely even when it's indented.

Reported-by: whoever-reported-it

Signed-off-by: Your Name

where that header line really should be meaningful, and really should be just one line. That header line is what is shown by tools like gitk and shortlog, and should summarize the change in one readable line of text, independently of the longer explanation.

Re: What a good commit message looks like (2011)

#26

Post by svckr »

Here's what, Tim Pope, our favourite vim nerd has to say about this: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messa... (Same, but with more words.)

A point of contention seems to be the choice of the imperative, at least for the subject line. While I'm really used to it, both when reading and writing, many people seem to strongly prefer past tense ("Fixed bug …" instead of "Fix bug …").

Re: What a good commit message looks like (2011)

#27

Post by raimue »

chris_7 wrote: post #17

The body of the commit message can be several paragraphs, and please do proper word-wrap and keep columns shorter than about 74 characters or so. That way "git log" will show things nicely even when it's indented. Software should help me, I shouldn't have to help it. Why doesn't git handle this formatting automatically? I shouldn't need to manually break lines for typographical (not paragraph) reasons.

That software is called a text editor and you can configure it to do the text wrapping for you.

More seriously, it is quite hard to wrap text correctly after you submitted it. For example people add manual line breaks for structuring text and to separate things like quoted commands from the rest. It would be much more cumbersome to go back after a git commit to fix this, probably in multiple iterations until you get the intended presentation instead of just doing it right from the start.

Re: What a good commit message looks like (2011)

#28

Post by jbattle »

nevon wrote: post #23
mojuba wrote: post #14

Should be noted, it is often tempting to describe everything about the change in the commit description rather than comments in the code. Remember, git commits disappear from sight pretty soon and become fossils, whereas there may be something important that should be said in the code itself.

Highly disagree. As long as the code lives, the commit lives.

until the git killer comes along and the team decides how much history they are willing to migrate. I've seen it happen every 5(?) years across several companies. Ironically it's always the oldest commit messages that turn out to be the most valuable because newer changes people remember

Re: What a good commit message looks like (2011)

#29

Post by chousuke »

nailer wrote: post #21
mojuba wrote: post #14

Should be noted, it is often tempting to describe everything about the change in the commit description rather than comments in the code. Remember, git commits disappear from sight pretty soon and become fossils, whereas there may be something important that should be said in the code itself.

Also: avoid using comments where proper names would suffice: // cleans responses function zrgfy(response){ ... } should be something like: function cleanResponse(response){ ... }

My rule of thumb in commenting is that I comment the why or how, not the what... Unless the what is sufficiently non-obvious, in which case it is usually prudent to have a really good explanation of the why, as well.

Re: What a good commit message looks like (2011)

#30

Post by lysis »

mojuba wrote: post #14

Should be noted, it is often tempting to describe everything about the change in the commit description rather than comments in the code. Remember, git commits disappear from sight pretty soon and become fossils, whereas there may be something important that should be said in the code itself.

A commit doesn't suffer from the same bit rot as a comment. Descriptions of how code changes doesn't shift as much as description of how code operates. If git blame, git log, and git diff are part of your workflow finding a git commit describing a piece of code is easy.
Post reply on HN