
How to write good Git commit messages - ashitlerferad
https://altcampus.io/blog/how-to-write-good-git-commit-message
======
swanson
I've worked for 10 years across 20 different commercial codebases. None of
this stuff about writing good commit messages really matters. No one reads old
commits. The "truth" is what the current code is doing and it doesn't really
matter how it got there.

I'm sure someone will say "but I use the history ALL THE TIME to source dive
and paragraphs of context are super helpful". This is not the case for 95% of
developers or projects so I can't really endorse spending time learning this
"best practice".

It's fine to be aspirational, but it's such a shame if people see posts like
this and think they are failures or "bad" developers or that this is a
widespread practice.

If it helps you personally or you have an open source project and you want to
help with a changelog, knock yourself out. But there are so many more
impactful skills to be learning or spending your time on if you're a working
developer in a typical environment.

~~~
knappe
I can't disagree with this more. Good commit messages are just so, so, so
important. Especially when I'm triaging an issue and have no other context
than the code itself. I want to know not the _what_ which the code gives me,
but also the _why_ which is what the commit message provides.

~~~
swanson
That's fine. I think your opinion is the majority opinion (at least online).
It just does not match my own experiences of reality.

You can and should value practices based on your context. But I will be the
asshole and ask if writing good commit messages is "so, so, so important" \--
what things are less important? Is it more important than a good test suite?
Well factored code? System documentation? Capacity for senior staff to answer
questions? These things cannot all be so important and, in my experience,
worrying about crafting amazing commit messages is way down the hierarchy.

~~~
realbarack
I'd certainly rather jump into a codebase with a great test suite and crappy
commit messages than a crappy test suite and great commit messages. But these
are apples and oranges. Keeping a great test suite is a constant fight against
tech debt, and testing things properly can be harder than the actual
implementation.

In contrast leveling up from the terrible "WIP WIP do the thing" to something
slightly less awful takes maybe an extra 1-2 minutes per commit. And every
time you do it you're doing your future self and future co-workers a huge
favor.

~~~
lowercased
There's a trend towards automation built around 'commits' that encourages this
sort of thing.

"WRITE BETTER MESSAGES".

but put WIP in the title so we know not to review it.

but ... do commit often, so we can get builds out. put WIP in the title so we
can decide to build with tests or not. or something.

Tying automation steps to 'commit messages' is begging for "WIP JUST
COMMITTING TO GET A BUILD OUT" messages, which people then complain about.

------
Vinnl
Maybe just as important: make sure the changes in a commit are related. `git
blame` is a criminally underused feature, possibly because the benefits only
become clear _after_ you've had the discipline of paying attention to what
goes in a commit. However, being able to pull up the context of related code
right from the context of the line you're looking at [1] (from my post at [2])
can be very valuable.

[1] [https://vincenttunru.com/img/Commits-are-
documentation/annot...](https://vincenttunru.com/img/Commits-are-
documentation/annotations.png)

[2] [https://vincenttunru.com/Spend-effort-on-your-Git-
commits/](https://vincenttunru.com/Spend-effort-on-your-Git-commits/)

~~~
graton
Many text editors now have this feature built in.

Myself I use vim and the vim-fugitive plugin. Being able to do ":Gblame" is
amazing. And then being able to step back in time to see what the code looked
like before this commit is great too.

------
IE6
Another good resource I always point my developers to:
[https://chris.beams.io/posts/git-commit/](https://chris.beams.io/posts/git-
commit/)

As someone who manages many codebases this combined with thoughtful squashed
commits allows me to (1) understand at a high level what each commit does, (2)
drill into each commit should I choose to in order to review what was done in
more detail, and (3) review a JIRA ticket relevant to the change (which often
times is more valuable than 1 and 2).

~~~
dchess
I was reminded of this resource as well since it is likewise what I use in
training folks to use git. This OPs post seems to be a condensed version of
Chris's advice.

------
nogabebop23
I promoted something similar to all teams at my company (I'm a manager of one)
and something that I thought was a no-brainer, common sense, easy win was met
with very strong resistance - and mine was even more basic than these
recommendations!

It's great to recommend and we should keep coaching and mentoring but
ultimately this is an area where I think you'd be better to go up the chain of
command until you reach a benevolent dictator who can mandate criteria. I'd
love to convince people based on the merits alone, but to paraphrase a common
observation in academia "the resistance is high because the stakes are so
low".

------
noahdesu
I'll take this further: I think that bad commit messages breed resentment.
It's highly context dependent, but needing to understand some code and its
historical context is already a big challenge. git-blaming your way back
through time only to encounter brain dump commit messages full of ambiguity
and non-essential information is excruciating. Writing good commit messages--
like any technical writing--is more art than procedure, and it's hard to do
well without feedback and revision. I believe that commit messages should be
subject to the same level of review as the code they are presumably
documenting.

------
graton
An important thing for me in a commit message is the "why" of the commit. Sure
it can state "changed foo to use blah". But why did they do that is often very
important information. Sometimes it is very obvious from the what, but
oftentimes it is not. The article didn't seem to mention this, or if it did I
didn't notice it.

I usually think a commit message should have a "what" changed and a "why" it
changed portion.

Of course putting this information in code comments may also be a wise thing
to do.

------
mrspeaker
How is "Do not end subject with a full stop" self-explanatory, but "Begin
subject with a capital letter" not self-explanatory? Makes me suspect the
author doesn't really know why they don't put a full stop ;)

Now I don't know why don't you put one! I vaguely to remember reading this on
the last "how to write good commit messages" blog and thinking it seemed fair,
but now I can't think of a reason. Why follow grammar rules for the start of a
sentence, but not the end?

~~~
rement
Would you add a full stop in an email subject? I think of commit messages like
an email. The first line is just the subject and sometimes that is all you
need. The body of the commit message is for describing other details.

edit: Another blog has a simple reason [https://chris.beams.io/posts/git-
commit/](https://chris.beams.io/posts/git-commit/)

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

> Trailing punctuation is unnecessary in subject lines. Besides, space is
> precious when you’re trying to keep them to 50 chars or less.

------
kentosi
For anyone questioning the imperative mood ("Add module x" as opposed to
"Added module x"), what helps me it to think of each commit as a patch being
applied.

When I think of a patch it's almost always a patch that will "do the thing"
rather than "did the thing".

------
glxxyz
I provided extended support on a custom system for about a year at a former
employer, where the whole dev team had left before I started. I once tracked a
bug down to a confusing line of code that looked like it shouldn't be there.
Removing this line fixed the bug. When I looked in the commit history, that
line was added as the only change in a commit that had no comment. I never
worked out what they intended, e.g. whether it was a fix for something else I
hadn't considered.

In fact, and this is probably hard to believe, I don't think there were any
comments anywhere in the commit history. Fun times.

------
bredren
I’m nearing completion of a three month solo project where I used this style
of commits, using it as an opportunity to practice doing this right.

Along the way I looked at some plugins for Pycharm and came across this commit
templating plugin that adds easy workflow for adding scope and commit type.
[https://plugins.jetbrains.com/plugin/9861-git-commit-
templat...](https://plugins.jetbrains.com/plugin/9861-git-commit-template)

Does anyone use commit message templating or style like this?

------
nikivi
My recent preferred workflow is to automate commits for docs + commits inside
feature branches with a tool I wrote
([https://github.com/nikitavoloboev/gitupdate](https://github.com/nikitavoloboev/gitupdate)).
It creates commits with the files changed as commit messages.

The branches ideally gets squashed with proper commit message when merging so
git history is clean. And no time is wasted writing commit messages that often
say whatever the code should already say.

~~~
naavis
In my experience commit messages shouldn't describe what was changed, they
should describe why the change was made.

~~~
nikivi
that is why you shouldn't waste time writing commit messages for where this
not much to `why` something has changed. (i.e. docs, refactors..)

~~~
bithaze
It's really not that much time though. "templates" and ".github" are examples
of such vague commit messages that they _require_ looking at the commit to
understand what changed. With a short, descriptive commit message, you can
just glance through the commit log.

------
ericol
I'm the half part of a 2 dev team.

Last year it took me around 3 months of internal discussions between us devs
and the project manager to get us to use a PR template in Github (The PM was
more or less sold on the idea).

Commit messages (Not mine, obviously) rarely amount to more than "Fixed
<this>".

And don't get me started on code comments (Non-existent, obviously).

The other coder is responsible for around 90% of the new code we ship these
days (The product is "frozen" because there is a better product developed by a
different and larger team, but we still have clients on this one) and I also
had to strong arm him into adding type hints for vars and functions (In PHP)
because he is _very_ fond of patterns (Think, SomeObjectFactoryFactoryFactory)
so it would make development with PhpStorm easier. So now the code is polluted
with

    
    
        /**
        * var $sometint integer
        */
    

that explain absolutely nothing.

------
ashton314
When writing the subject line for a commit, I like to imagine myself
explaining what I'm doing to a coworker, and I start off by saying, "applying
this commit will…" and then type whatever comes after that. This explains the
imperative tense. (Wait… is imperative a mood or a tense?)

------
jmilloy
The important parts are

    
    
      * write a short title, starting with a verb
      * include additional information from most important to least important
    

It just doesn't matter if you write "Adds" or "Add" or "Added", use capital or
lower case letters, if you use full-stops, if you include tags (like BUGFIX or
FEATURE) or issue numbers. Obviously, if you or your company decides to
require anything specific, that's fine, but they are just details with respect
to "good commit messages".

And extra info is not very useful if it isn't well-organized. In particular, a
narrative is not suitable for technical writing.

------
llamataboot
With the popularity of squash and merge these days, I feel like atomic commits
have gone by the wayside.

Personally, though I was in the "comments are running code and should never be
used" camp for a long time, these days I'm more inclined to want a concise and
clear comment on a particular thorny bit of code than a commit message

Tying a PR to an issue ticket where the conversations actually happened to
come to consensus on how a feature would work or what tradeoffs were made is
also helpful

A commit message in and of itself just doesn't have the bandwidth to give much
useful context, and now with all the squashes happening, hard to see what
commit did what

------
autogenerated
I think the Go guideline to commit messages is exceptionally good:
[https://golang.org/doc/contribute.html#commit_messages](https://golang.org/doc/contribute.html#commit_messages).

Also: Rob Pike's Google internal rant on the very same topic
[https://groups.google.com/forum/#!topic/golang-
dev/6M4dmZWpF...](https://groups.google.com/forum/#!topic/golang-
dev/6M4dmZWpFaI)

------
ed25519FUUU
I think there's a serious problem with people bikeshedding git. To squash or
not squash, the types of commits, the messages in them, etc, etc ad nuasuem.

I just want to easily be able to roll your changes back if there's a problem.
That's all. With good tests, git bisect will find the issue regardless of how
fancy and well written your commit messages are, or how squashed or un-
squashed your commits are.

~~~
joshmarlow
I see where you're coming from, but I would disagree on one thing - I always
thought squashing wasn't that important until I tried to use `git bisect` in a
project and found that a sizeable number of WIP commits didn't build
(basically had to abandon using bisect).

So I think there's a tooling reason for squashing - more effective use of `git
bisect`.

------
brlewis
For purpose 2 of good messages, "Help in maintaining a feature log", do folks
here have experience with
[https://www.conventionalcommits.org/en/v1.0.0/#summary](https://www.conventionalcommits.org/en/v1.0.0/#summary)
?

------
lukevp
I prefer commit messages to be of the form

#issueid - summary of issue

\- additional details

\- more details

Without a blank line anywhere.

This makes it really easy to review in graphical git clients because the
hyphens collapse into a single line like this:

#issueid - summary of issue - additional details - more details

Putting a blank line makes this rollup not happen.

------
boogies
Tiny tip: the 's' in 'changes' is the fiftieth character in the top commented
out instruction line git puts immediately below your commit message.

------
ravedave5
Adding "why" to the message isn't even mentioned. Which is better:

Updating the foobar threshold Updating the foobar threshold to improve
performance.

~~~
williamdclt
The why traditionally goes into the body of the commit message

------
tobyhinloopen
I approve this message

