
What a good commit message looks like (2011) - ziodave
https://github.com/torvalds/subsurface-for-dirk/commit/b6590150d68df528efd40c889ba6eea476b39873
======
chris_7

            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.

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

~~~
chris_7
Web browsers line break text dynamically just fine - as do, well, text
editors.

Using a text editor to automatically embed line breaks doesn't fix the
problem: embedding line breaks in text for formatting is wrong semantically.
Hard line breaks should _mean something_. Now I can't reflow the text to
display it on a web page in a normal font, because I can't be sure of which
line breaks are meaningful, and which are formatting.

~~~
masklinn
Except now you need everything to handle _textual contexts_ because while I do
want my nice paragraph of text to be wrapped, I don't want my code snippet to
be wrapped at all, and I want my nested list to be correctly intended at
wrapping.

~~~
greenhatman
I guess we want to use markdown in commit messages then.

~~~
masklinn
That provides absolutely no help. Markdown-formatted messages doesn't give you
a plain-text renderer and text layout engine.

------
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 <youremail@yourhost.com>

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.

------
struppi
Recently, I try to write the first line of my commit messages so they describe
what the system now does, compared to before the commit. This makes reading
the history much more fun. Like:

    
    
        Validation of email addresses now sends a test email to the user, instead of the old regex that never worked.
    

This style does not work for all kinds of changes, but when it works, it
creates a nice history of how the functionality of the system grew...

~~~
TheDong
Including the old bit is meaningless noise there.

I'd use something like "Improve email validation" or "email: send a test email
as validation" or such.

The body is where you can describe previous behaviour and give more details.

~~~
Cthulhu_
Yeah that. I'd have it describe what the commit does in the subject, and both
the why and how in the body:

Validation of email addresses now sends a test email to the user, instead of
the old regex that never worked.

> Send test email to user for email address validation > > This change was
> done because the old regex never worked; see also {link} and {link} for more
> information.

as an example. Ideally the header also contains a hint to the module the
change was done in, etc. The linux kernel commits take this to (what comes
across to me as) the highest levels.

------
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...](http://tbaggery.com/2008/04/19/a-note-about-git-commit-
messages.html) (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 …").

~~~
gregmac
More importantly, the correct way is _the way that is currently being used_.

If the project uses past tense, use it. If you want to change the convention,
that's okay too, but everyone has to change.

It's exactly the same issue as coding style. If you can look at code or commit
messages and figure out who wrote it based purely on style/formatting, you're
doing it wrong (or rather: the person using the inconsistent style/format is).

~~~
greenhatman
Tenses in commit messages seem a bit pedantic and inconsequential. It doesn't
really affect much. Unlike tabs vs. spaces, where mixing would cause a mess.

~~~
Analemma_
Most code formatting issues are pedantic and inconsequential. Never stopped us
from fighting to the death about them ;)

------
binarnosp
I open an issue for every feature, bug or enhancement, then I mention the
issue in the commit followed by a short description of the changes. I wrote
down a procedure that I follow for every commit [1].

This allows me to keep the commit line short and to see the commits history
related to the resolution of a bug or feature.

When using Gitlab, Bitbucket or Github the issues and the commits are cross-
linked (example: [0]).

[0]
[https://bitbucket.org/binarno/imebra/issues/162/](https://bitbucket.org/binarno/imebra/issues/162/)
[1] [https://imebra.com/wp-
content/uploads/documentation/html/sop...](https://imebra.com/wp-
content/uploads/documentation/html/sop.html#sop-fixbug-2-fixing-a-bug)

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

~~~
karim
I think that on the contrary, everything should be in the commit. The commit
message is dated, it has an author and a context. How often do you come across
stray comments which shouldn't be here because the code got refactored away?
Commis are often just a git blame away anyway.

~~~
Cthulhu_
Except when a line has been changed over a longer period of time. Although
maybe I'm just not comfortable with tracking history too much, because in the
applications I generally work on (customer-facing webapps) we generally don't
need to look back in history too much.

------
gempir
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

~~~
superzadeh
even better systems allows to link tickets to commits.

~~~
gregmac
Not the OP, but our JIRA instance does this. From a ticket in JIRA, you can
see any commits, branches or pull requests mentioning that ticket.

We also use this convention with gitflow, so our branches are named eg,
feature/PROJ-1234-added-new-ui or bug/PROJ-2345-fix-new-ui. This also lets
JIRA find and link them, and makes pull requests get the ticket number in
their title by default as well (since its based on branch name).

The last bit is just a short human-readable thing to make branches easier to
look at and find, because the initial way we started using gitflow:

    
    
        feature/
          feature/PROJ-2286
          feature/PROJ-2352
          feature/PROJ-2367
          feature/PROJ-2382
          feature/PROJ-2385
        bug/
          bug/PROJ-2240
          bug/PROJ-2323
          bug/PROJ-2393
    

is completely unintelligible.

------
abstractbeliefs
For those who aren't familiar with the kernel process, what's the Reported-by
line? Simply the reporter of any original bug that the patch was written to
fix?

I understand that the Signed-off-by line is equivalent to a CLA, right?

~~~
tych0
Yes, Reported-by is the original reporter.

Signed-off-by is fallout from the SCO lawsuit. It has nothing to do with
agreeing to any sort of CLA; it's just another way to confirm that the code
was written by the person in Signed-off-by, or that the person in Signed-off-
by thinks it was created under appropriate open source conditions (e.g. the
company who paid the developer to write it is okay with it being released).

------
jordansmithnz
Nice. At an old job, I got a little bored, so I'd spend time crafting
wonderful commit messages. Most of them contained puns, some very subtle, some
less so.

In regards to commit ethos, I'm not sure I agree with all of the statements
made. To me, something simple/concise, that others will understand, but not
lacking in key info, is much better than several paragraphs explaining the
same thing.

------
leotartari
This is still relevant, as my friend Cesar wrote about it just the other day
(with a very similar title) » [https://hackernoon.com/what-makes-a-good-
commit-message-995d...](https://hackernoon.com/what-makes-a-good-commit-
message-995d23687ad#.5sc2xvg92)

------
collyw
One problem with this is that git gets used as a deployment tool as well as a
version control system.

Trying to get something to run on Heroku involved making lots of small changes
just to get things to run on the server the same as on my dev machine.

When you do that 10 or 20 times the commit message become somewhat
meaningless.

~~~
vinhboy
I also commit like 20 things to get Heroku working properly. But after I am
done with that, I `rebase` it into one commit. Then I push it into my
`origin/master`, and force push `heroku/master`.

------
msimpson
The link within that README leading to what "Signed-off-by" means is now
broken. Use:

[https://gerrit-review.googlesource.com/Documentation/user-
si...](https://gerrit-review.googlesource.com/Documentation/user-
signedoffby.html)

------
dallamaneni
I made this git commit template sometime ago. Check it out if it is of any
help:
[https://gist.github.com/adeekshith/cd4c95a064977cdc6c50](https://gist.github.com/adeekshith/cd4c95a064977cdc6c50)

------
__strisk
don't use git commit messages as "dear diary" sort of things.

For example:

"I fixed the button issue on the homepage. Still, need to center the title."

would be better written as:

"fixes button issue on homepage"

Always think about what that commit does to the codebase. This is obviously
for single-line commits. I suppose it would be okay to "dear diary" in the
commit body. You can provide rationality or context in the commit body.

~~~
wolfgang42
My recommended style is:

    
    
        Fix button issue on homepage
        
        This allows the title to be centered,
        as the button will no longer collide with it.
    

Then, in a subsequent commit, center the title and put a reference to this one
if you feel it's important, like so:

    
    
        Center the title on the homepage
        
        It wasn't previously because it would collide with the button,
        but that was fixed in f00b1f.

------
fit2rule
My commit messages are (usually) one-line, starting early in the sentence with
the focus of the effort, and ending with a clear statement of what happened.

------
StapleHorse
Relevant xkcd [https://xkcd.com/1296](https://xkcd.com/1296)

I once wrote "commit". A fellow coworker still makes fun of me for that,
joking of course.

------
dang
Url changed from
[https://gist.github.com/matthewhudson/1475276](https://gist.github.com/matthewhudson/1475276),
which (kind of) points to this.

------
Avshalom
>74 characters

path dependency is hell of a drug.

~~~
merb
if you open a terminal window on mac with any kind of display 1080p, 4k
whatever with any resolution you will still get a 80x24 terminal by default.
Which is the whole purpose of `git log`. Using it on a terminal / ssh session
/ whatever.

~~~
mamadrood
I use ~80 cols terminal because everything is designed to fit in 80 anyway.
More than that and it's just whitespace.

