
How to Write a Git Commit Message - pwg
http://chris.beams.io/posts/git-commit/
======
ThePhysicist
The biggest problem with commit messages: They lie.

The main reason for this is that most people tend put more than one atomic
change into a single commit, but in the message they often only mention the
"main change" which they introduced with the commit. This in turn makes it
much harder to find out which commit introduced a given problem into the code
base since people will usually read the (incomplete) message of a given commit
and think "the problem can't be here because this commit only did X" while it
actually did Y & Z as well. So, personally, I think we could as well abandon
writing commit messages entirely and instead make sure that individual changes
are small enough so that we can figure out what happened by looking at the
actual code instead.

As an example, if you look at individual commits in the Django project (such
as this one:
[https://github.com/django/django/commit/e7e8d30cae9457339eb4...](https://github.com/django/django/commit/e7e8d30cae9457339eb49ae8584e82ff0a038e99)),
it is often much easier to figure out what happened by looking at the file
diff than the commit message.

A tool that could summarize changes in source code using advanced (semantic)
diffing instead of line-by-line diffs would make this much easier of course.

~~~
jumpwah
With magit, it's easy to only stage individual 'hunks' so that you can have
only the relevant parts of a file staged. And so this problem goes away.

I also imagine it's easy to do this in fugitive as well.

It's probably also possible on the cli, but I imagine that would be too 'hard'
or time consuming, hence you will probably start to be lazy about doing it
correctly.

~~~
aninhumer
>It's probably also possible on the cli, but I imagine that would be too
'hard' or time consuming, hence you will probably start to be lazy about doing
it correctly.

I do it all the time, you just use `git add -p` and it steps through hunks
letting you stage them or not. As long as you don't make too many changes
without committing, it's not particularly tedious.

~~~
abalashov
This was the 'killer app' that compelled me to switch to Git from Subversion
back in the day, rather than anything else about Git intrinsically. The
ability to organise my commits logically rather than temporally (i.e. not just
as a stupid log of change over time) was like night and day.

~~~
viewer5
> ability to organise my commits logically rather than temporally

I'm just getting started with Git; how do you do that? I googled it but
nothing jumped out at me.

~~~
sfilipov
He referred to what the GP said - use "git add -p". Here's some introduction
(I haven't watched it myself and can't comment on the quality):

[http://johnkary.net/blog/git-add-p-the-most-powerful-git-
fea...](http://johnkary.net/blog/git-add-p-the-most-powerful-git-feature-
youre-not-using-yet/)

------
networked
Out of all common advice on Git commit messages always using the imperative
mood in the title I find the hardest to agree with. Describing your own
actions as a committer in the imperative may sound strange, true, but there is
the worse problem of making less obvious the distinction between the actions
of the system and those of the committer.

In my own projects I use the imperative when describing the actions the system
should perform ("Don't warn user about missing cache directory") but use the
indicative mood when describing my own actions ("Removed unnecessary cache
directory warning"). I've noticed that some projects use the imperative for
both cases and I suspect this introduces a degree of cognitive overhead to
scanning the commit log. One solution to this problem would be to never
"address the system" in the commit title but I find that that is often the
shortest and the most expressive way to describe an update.

~~~
seiji
I think GitHub has broken us a lot here.

Commits, when extracted from the repository, need to stand on their own.
Example: sending a commit over email. Then you look at a commit message and
you _do_ ask "What does this commit do?" The commit doesn't "removed
unnecessary things" because that just sounds wrong—the commit didn't _already_
do things before it existed.

The weirdness comes from describing what the author already _did_ to even
create the commit versus what someone encounters when they read the commit for
the first time. Your historical actions don't matter in writing results, only
future readers matter for what they discover the patch _will_ change.

~~~
davexunit
Agreed. GitHub has really done a lot to harm the quality of commits. Their
tools emphasize looking at and commenting on the total diff of the patch set
rather than inspecting each commit on its own. I tried commenting on the
patches themselves once only to realize that the pull request page didn't show
them and they were hard for the author to find. Unfortunately, it doesn't seem
that GitHub is willing to change their code review tools since even Linus
Torvalds complained about them and nothing important was changed.

~~~
piotrkaminski
Luckily, since GitHub has a pretty extensive API, this leaves the way open for
third-party code review solutions like
[https://reviewable.io](https://reviewable.io) (disclosure: I built it). But
yeah, considering how long it took them just to put in a split view, I
wouldn't expect a whole lot of improvements in the foreseeable future...

------
divan
Does the majority read commit messages as "If applied, this commit will..."?

I always treated log messages as a history of events, i.e. describing what had
happened in the past - this commit "fixed" something, and this one "changed"
something, "refactored", "implemented", etc.

~~~
seiji
A commit object is a container talking about itself. You don't talk about your
present state in the past tense.

~~~
GavinMcG
A commit object is a container of changes. A commit message is a label placed
on that container by whoever packed it. It's not the container talking about
itself – it's a programmer labeling something for other programmers to read
(in the future) about something they have already done.

~~~
jarfil
That would be the egocentric view, instead of letting the commit stand on its
own.

------
josteink
Magit for Emacs helps you maintain some of these standards if you enable
flyspell for git-commit-mode.

And obviously Emacs is my editor of choice for everything, git commits
included.

~~~
davexunit
+1 for Magit and Emacs. They are my not-so-secret weapons.

------
jph
We advocate also using hashtags and URLs in the commit message body.

Our hashtags correspond to specific areas such as #analytics, #localization,
#api. These hashtags are easily searchable by the respective teams, and we
also use simple shell scripts that categorize by tag, e.g. "List all the
changes related to #analytics".

Our URLs link to the corresponding tasks in Asana, Jira, etc., and also to any
relevant background information such as RFCs, ISO standards, NIST docs, etc.

~~~
agumonkey
Saw this blog last week : [http://ericjmritz.name/2015/05/27/my-global-git-
commit-templ...](http://ericjmritz.name/2015/05/27/my-global-git-commit-
template/)

He uses a template with a few metadata, and tags too. In an older entry he
mentions using a special WIP tag for successive sequences of iterative changes
toward a fix too.

~~~
jarfil
Isn't WIP what branches are for?

~~~
agumonkey
I guess I don't branch enough then.

------
dbbolton
>3\. Capitalize the subject line

>4\. Do not end the subject line with a period

>5\. Use the imperative mood in the subject line

I can't help but feel that these three "rules" should be removed and placed in
a separate list of style guidelines since "breaking" them is hardly going to
make your commit message unreadable.

E.g.:

    
    
        5ba3db6 fixed failing CompositePropertySourceTests.
    

would still good enough in my book. I think _consistency_ is actually more
important than following those three prescriptions specifically. It only
becomes an issue if you capitalize some subjects but not others, alternate
between imperatives and past participles, or use different punctuation styles.

------
revelation
"Fix failing $test" and "Add tests" seems like a commit message anti-pattern.
A failing test likely has its failure rooted in an actual problem that you
could be describing instead, and a commit message simply stating that you
added "multiple tests" lacks a rationale for each and every test added.

------
lisa_henderson
A commit message should answer the question "why?".

In the article they ask "Which would you rather read?"

I would prefer to read the first commit message they offer as an example:

"Re-adding ConfigurationPostProcessorTests after its brief removal in r814.
@Ignore-ing the testCglibClassesAreLoadedJustInTimeForEnhancement() method as
it turns out this was one of the culprits in the recent build breakage. The
classloader hacking causes subtle downstream effects, breaking unrelated
tests. The test method is still useful, but should only be run on a manual
basis to ensure CGLIB is not prematurely classloaded, and should not be run as
part of the automated build."

That is informative and gives me the information that I need. It answers the
question "why?". And yet, this commit message is held up for criticism. And
then, this is given as a recent example:

"Rework @PropertySource early parsing logic"

I have no idea what happened in that commit. And this commit does not answer
the question of "why?".

I disagree with this entire article. The examples of "bad" commits are the
one's that I would want my co-workers to write. The example of "good" commits
are the kind that would make me angry with my co-workers.

Verbose commit messages are not useful because they are verbose, but a commit
message should answer the question "why". Commit messages that answer the
question "why" tend to be a bit longer than commit messages that fail to
answer that question. I would much rather read a verbose message that answers
the question of "why?" than I would read a short message that fails to answer
that question.

~~~
krisdol
Agreed -- when I read the article, I found the first set of commits more
valuable than the second. Having short commits is better than long commits,
but not at the expense of information. I don't need commits that use the words
"updated, fixed, added" \-- if I'm looking at `blame` I know something was
updated/fixed/added. What matters is how something was changed, and sometimes
why it was changed.

Write commits that help your coworkers figure out why the code looks the way
it does. If you're writing "update FooBarFactory to fix Bug4" you're
essentially wasting my time by using git to narrate the obvious.

------
stared
Again, recommending the angular style:
[https://github.com/angular/angular.js/blob/master/CONTRIBUTI...](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#commit-
message-format)

As (IMHO) the most important thing is where (out of many modules) is the
change and of which kind (fix? a new feature? refactoring? only some docs?).

------
bjourne
Most of those rules are good. But don't lose focus on why you are writing
commit messages in the first place which is to help some poor programmer many
years from now to track down a bug in the code you wrote.

E.g His fourth rule to great commit messages is "Do not end the subject line
with a period" But if you think it matters if there is a period at the end of
the subject line or not, then you might have a bit of an anal retentive
streak. :) Keeping your opening brace placements and indentation consistent,
that's important because code is easier to read if it is formatted
consistently. So some details matter and some details do not. Periods at the
end of subject lines in commit messages is of the latter category.

------
Retr0spectrum
The page was very slow to load for me. Here's a mirror in case it goes down
completely: [https://archive.is/LGRwO](https://archive.is/LGRwO)

------
tacone
I have some problem with this:

> Use the imperative mood in the subject line

Sometimes, you don't have or don't want to link to a bug tracker bug. So it
gets unpractical to write something like "fix the window that didn't close at
the click of the button". It would be much better to write "Fix: button click
did not close the window". This is even more true if you _have_ to write
commits in a latin language.

I guess the bottom rule is synthesis and assertiveness should be only
considered as a preferred method, not an hard rule.

~~~
JoshTriplett
> So it gets unpractical to write something like "fix the window that didn't
> close at the click of the button".

Imperative style normally produces more direct messages than that; talk about
how it behaves now, not how it used to:

"Close window when button clicked"

Or, assuming "button" here means "close button":

"Close window when user clicks close button"

~~~
greg0ire
Yeah, plus, the fact that you fix something is the "why" part of your commit
message, it should go in the body. The result could look like this :

> Reduce overlaying div element width > > This caused a bug on some devices :
> the div would overlay the close button, causing it to be unreachable.

I think that commit message that begin with "fix" are often not very good.
Basically, you're saying "It was broken, this commit fixes it", not what was
broken nor how your commit is _supposed_ to fix it (yeah because sometimes,
people think they are fixing something and actually create another bug in
another part of the thing).

~~~
tacone
Interesting, I'll think about that.

------
dougdonohoe
In the past few teams I've led, the requirement was to include a JIRA ticket
number in the commit message. With tools like Fisheye, you can click from the
commit message to the JIRA and get much more context about the particulars of
the commit. It worked exceedingly well. The point is that there is only so
much context you can put into a commit message. Sometimes the context lives
outside the system and good tools support like Atlassian's suite makes life
easier.

~~~
nirvdrum
A lot of people do something similar on GitHub. If you're going to do this,
please include the issue subject in the commit message somewhere. "Fixes #135"
is absolutely meaningless outside the context of whatever tool. And it
absolutely falls apart if the project lives long enough to change issue
trackers.

~~~
fenomas
Much agreed. "Fixes #123" makes sense for _pull request_ messages, but the
commit messages should be verbose!

------
webo
When you work on a team that requires code reviews (pull requests) before
every check-in, the "body" portion of the commit does not really make sense as
the developer pretty much has to include that information in the code review
description either way.

Most teams automatically put a link to the corresponding code review in the
commit message/body.

~~~
unfunco
I'd still prefer a body with a good commit description, since review
descriptions are not attached to the history.

I've been thinking about this a little recently, the conversations that
determine the direction of a product are not part of the history, if a
repository is shared there's no way to see that information without going
through emails, or going through issues on GitHub or Bitbucket or whatever
else.

~~~
webo
Is this something we can change though?

As you mentioned, these conversations happen everywhere including offline
meetings and hallway chats.

------
themckman
I like to point people to the Linux kernel `git log`[1] when talking about the
value of good commit messages.

[1]:
[https://github.com/torvalds/linux/commits/master](https://github.com/torvalds/linux/commits/master)

------
mdaniel
I thought for sure it would be about this recently announced project, which
also cited Tim Pope: [https://github.com/m1foley/fit-
commit#readme](https://github.com/m1foley/fit-commit#readme)

------
jorisroovers
I recently started working on a tool that checks for this and more :
[https://github.com/jorisroovers/gitlint](https://github.com/jorisroovers/gitlint)

------
Vintila
What I want to know is how to write good commit messages when you're first
building your _thing_. Most of your code is unwritten and what is written is
constantly changed to improve the interface(s).

------
Kiro
> and doing the right stuff with git when you rename one

What is he referring to?

------
silverwind
I have to disagree on "Capitalize the subject line". If you're using lower
case consistently, it's an unnecessary stroke of the shift key.

~~~
Pyxl101
Commit messages sometimes need to be longer to explain something. When that
happens, it's nice for the subject to be the first sentence (possibly with the
rest on another line).

    
    
      Don't warn the user about foo.
      
      The foo warning is superfluous because ...
    

> it's an unnecessary stroke of the shift key

This is not a good reason to argue for a style convention. The effort or time
of pressing "shift+letter" is no greater than simply pressing "letter" for all
experienced typists since they are pressed simultaneously and the decision to
capitalize a letter and execute the necessary keypress is completely automatic
and fluid. If we were discussing rarely-used symbols and keystrokes then the
analysis might be different.

There is great value in following the language's style convention since its
readers are familiar with that convention. Upper case denotes the beginning of
a sentence. When you scan a series of lines beginning in upper case, there's a
visual cue that they're each their own unit, as opposed to (for example) the
wrapping of a previous line.

    
    
      Don't warn in case foo
      Update bar dependency
      Warn user when baz
    

These scan better to me as a series of three independent thoughts than the
equivalent in lower case, which seems like a poorly written haiku:

    
    
      don't warn in case foo
      update bar dependency
      warn user when baz
    

Personal preference might differ, but my opinion based on seeing many
variations is that programming texts such as documentation, commit messages,
etc., are most readable when they follow the syntax and style of regular
English text, to leverage all of the standard cues that the reader is familiar
with. Readability usually suffers when one breaks from convention.

Lastly, following regular conventions gives you the advantage that you can
copy/paste text across various scenarios without having to change it. Need to
reference a commit message in an email? Well, just copy it in. No need to mess
with the capitalization. All things considered I see no good reason to begin
documentation or commit messages in lower case given the overwhelming
conventions to the contrary that exist in our language.

