
Write good git commit messages - pafo
https://juffalow.com/other/write-good-git-commit-message
======
scrollaway
Writing good commit messages is one of those things that IMO make the
difference between a dev who produces good code, and a dev who produces high
quality work in general.

The git log is one of the main entry points to an open source (or closed
source, in fact) project. Following them tells a story, and can help you
understand decisions made.

Imagine you have two projects to bisect. One of them has clean, atomic and
descriptive commits. The other has a git log that looks like this:
[https://github.com/pypa/pipenv/commits/master?after=d4d54eeb...](https://github.com/pypa/pipenv/commits/master?after=d4d54eeb39ef45a9b68c78b8fc8f66c3f5396691+1154)

I know which one I'd want to debug. This is also the primary reason why I
highly dislike merge commits: They make git logs extremely unreadable.

The thing is that writing clean commits is something that is extremely easy to
do. Unlike docs and tests, it's not more work (it's less, in fact) and it's
not something to continuously maintain as the code changes. It's an immediate
improvement you can make to your development habits that will have a
consequential improvement to your QOL. You _will_ catch bugs doing this!

(Tip when writing atomic commits: Use `git add -p`. That lets you stage patch
hunks.)

~~~
sly010
Writing the good quality commit message is not that hard and is sometimes
actually enjoyable (after all i get to brag about this feature / bugfix /
solution).

What does cause a lot of mental overhead (and consider myself a decent
engineer) is creating commits that have a single purpose in the first place.

Working on a new feature I often have to refactor something, and while I am at
it, I clean up some related parts. That is at the minimum 3 commits applied in
the correct order, sometimes over different branches. At that point there is a
lot of `git add -p` and `git stash apply` going on, which takes considerably
more mental energy while you see some colleagues getting away with `git commit
-a`.

Writing good commit messages itself is the reward for creating good commits.

~~~
awolf
Rather than `git add -p`, I suggest creating a second clone of your repo,
staging your foundational refactor changes in the second repo, creating and
merging your commits there, and then rebasing your working branch.

This makes sure you can fully test your refractors and that their change sets
stand alone.

~~~
dllthomas
If you know your way around git well enough that you're not going to be
screwing up _repository_ state in ways you can't fix, there's no reason to
operate from separate clones - check out git worktrees :)

~~~
bacon_waffle
Thanks for that! I've occasionally thought a feature like this would be
possible and helpful, but hadn't encountered it until your mention.

~~~
dllthomas
I felt the same way when I stumbled across it in a man page :)

------
navinsylvester
I use the following convention to start the subject of commit(posted by
someone in a similar HN thread):

    
    
        Add = Create a capability e.g. feature, test, dependency.
    
        Cut = Remove a capability e.g. feature, test, dependency.
    
        Fix = Fix an issue e.g. bug, typo, accident, misstatement.
    
        Bump = Increase the version of something e.g. dependency.
    
        Make = Change the build process, or tooling, or infra.
    
        Start = Begin doing something; e.g. create a feature flag.
    
        Stop = End doing something; e.g. remove a feature flag.
    
        Refactor = A code change that MUST be just a refactoring.
    
        Reformat = Refactor of formatting, e.g. omit whitespace.
    
        Optimize = Refactor of performance, e.g. speed up code.
    
        Document = Refactor of documentation, e.g. help files.

~~~
hmcdona1
This is similar to the Conventional Changelog:

[https://github.com/conventional-changelog/conventional-
chang...](https://github.com/conventional-changelog/conventional-changelog)

I often use a customized Commit Lint in combo with Husky to enforce
conventional changelog messages:

[https://github.com/marionebl/commitlint](https://github.com/marionebl/commitlint)

[https://github.com/typicode/husky](https://github.com/typicode/husky)

You can also throw in something like the Commitizen cli for newcomers:

[https://github.com/commitizen/cz-cli](https://github.com/commitizen/cz-cli)

------
BlackFly
These sorts of prescriptions always strike me as the sort of fastidiousness
that some software developer types are stereotyped with.

Just once I would like to read someone that takes a descriptivist approach to
commit messages instead of a prescriptivist approach. I would prefer even a
scientific approach where someone sets out to measure if these sorts of
measures have a concrete measurable effect beyond people's anecdotal
preferences.

Prescribing what a commit message can look like implicitly prescribes what a
commit can look like and that turns a flexible tool into a less flexible one.
For many people, lack of flexibility can be a feature... but it is an
empirical question on whether or not if it aids development and I am not
really aware of anyone trying to measure these things. In the spirit of "No
silver bullet," by Fred Brooks, I am skeptical that between the code comments,
the code documentation, and the ticketing system that the git commits are
adding much.

~~~
majikandy
Best comment I read so far on this. Taken a stage further, a well written
codebase of self-documenting tdd’d clean code and commit messages become
moderately useless. For all the effort they take and the rare occasion they
aid in finding something useful, a completely blank entry for every commit is
arguably more efficient. In the spirit of it only taking a few seconds whilst
your head is in that space, a short brain dump of what it is in any format you
like is an excellent and efficient choice.

------
jimmytucson
My take: these aren’t good commit messages. The verb isn’t supposed to be what
you did, otherwise it would always be “add” or “change” or “fix”. The verb is
supposed to be what the program does thanks to this change. E.g. “Check server
fingerprint”, not “Add server fingerprint check”.

We already know you changed or added something, it’s a git commit.

~~~
MatekCopatek
But how would you name the commits that fix, refactor and remove that same
feature? "Check server fingerprint with less errors", "Check server
fingerprint in a different way" and "Check server fingerprint no more"?

~~~
matthewmacleod
“Handle timeout errors when checking server fingerprint”, “Use new API
endpoint for server fingerprint”, and “Replace server fingerprint checking
with magic”.

You can still use those verbs, but the interesting thing in commit messages is
_what they do_ , rather than what changes you made.

A commit message is really like a small note to future contributors; it’s not
always easy to write them, but it’s always worth thinking about them from the
perspective of someone who is looking at them two or three years hence.

~~~
usrusr
But "Replace server fingerprint checking with magic" has clearly crossed the
line from "the verb describes what the code does" to "the verb describes what
the developer did".

"Note to future contributors" is spot on of course. The best way to write
better commit messages is to consume the existing corpus as often as possible,
e.g. by never trying to understand code without the blame column active in
your editor of choice.

My preferred format is a condensed why-what, consisting of "$verb $ticket
$wherein":

$verb would be the developer activity, like fix/optimize/remove/.., and it is
mostly there to make it clear that the rest of the message should not describe
developer activity.

$ticket would reference your beloved issue tracking system (an additional
short keyword describing the issue doesn't hurt as a checksum and to prevent
excessive referencing, but it has to be optional because a bad keyword is
worse than none).

$wherein would be the customary quick rundown of how the code is supposed to
work, expect future readers to only read the beginning.

I like this order because it gives a rudimentary sentence structure to the
formulaic parts and positions them at the beginning where they can never be
pushed below the fold by the potentially rambly description of the code.
Anything more complicated than that will degrade harder when rules are not
followed to the letter. Perfect is the enemy of good.

------
chatmasta
I'm disappointed that the mods changed the title from "Write good commit
message" (which is the actual title of the article) to "Write good commit
messages," because I think this was an intentional, subtle joke by the author
to make the title resemble a commit message.

------
cygned
I always recommend this article: [https://chris.beams.io/posts/git-
commit/](https://chris.beams.io/posts/git-commit/)

The recommendations are the same, it's longer and provides more rationale at
some points.

~~~
CydeWeys
Yeah, it's the same advice, just Chris Beams did it over 4 years earlier.

This is the article I always link people to on my team when explaining how to
write commit messages. My company doesn't have a style guide for this exact
thing, so this article is what I've been using. And the results are here:
[https://github.com/google/nomulus/commits/master](https://github.com/google/nomulus/commits/master)

------
NateEag
Good commit message summaries are important (the short one-line overview).

Including links to the issues the commit relates to in the body is important.

That said, most of what I've seen in large commit message bodies (like the
ones I used to write) really belongs in the patch itself, as changes to the
project's formal documentation or source code comments.

If you thought it was worth explaining why you made the change as you did, it
likely means the choice was not obvious.

If it wasn't obvious, the explanation belongs in the project proper, where
anyone who cares can see it, not tucked away in a commit message that may be
hard to discover four or five years down the road.

If it's a decision that impacts UI, the justification belongs in the project
specs or docs, where people besides devs can find it (I like to keep my specs
and docs as plaintext in the repo and render them to HTML for non-devs to
reference).

If it's a strictly internal decision, like what algorithm you chose for a
function's internals, you should explain why right there instead of hiding
valuable knowledge in the commit message.

~~~
u801e
> If it wasn't obvious, the explanation belongs in the project proper, where
> anyone who cares can see it

A lot of times, code comments may not be updated along with code changes, so
they may not be accurate. A commit message is associated with a change at the
time it was made.

> not tucked away in a commit message that may be hard to discover four or
> five years down the road.

The git blame command makes it pretty easy to see what commit introduced a
line of code and it also makes it easy to see the context of the change (the
rest of the diff).

> If it's a decision that impacts UI, the justification belongs in the project
> specs or docs, where people besides devs can find it

There's no reason that it can't be recorded in both places.

> If it's a strictly internal decision, like what algorithm you chose for a
> function's internals, you should explain why right there instead of hiding
> valuable knowledge in the commit message.

But let's say you want to make a change to the method and you have a comment
explaining the change there. Now you make a change to the method and some
other part of the code breaks. If you looked at the commit message instead,
you can get an explanation and the context of the change (meaning the other
parts of the code that relied on the original change you're looking at).

~~~
NateEag
> A lot of times, code comments may not be updated along with code changes, so
> they may not be accurate. A commit message is associated with a change at
> the time it was made.

Code review ought to catch comments that haven't been updated.

Further, if a change would have caused the comment to become stale and
irrelevant to the project's current state, the commit message would have the
same problem. Where you keep it doesn't impact that.

If you want to look at historical states, the comment itself is saved
perfectly in the old commit, just like the commit message would be.

> The git blame command makes it pretty easy to see what commit introduced a
> line of code and it also makes it easy to see the context of the change (the
> rest of the diff).

I am intimately familiar with `git blame`, and have used it for code
archaeology in puzzling codebases over a decade old.

It sure beats having nothing, especially when you configure it to ignore
whitespace changes and use Magit's lovely blame interface to move through
history quickly, but it can still be a pain to figure out where code really
originated from.

If the originating commit gives me a link back to the issue that started it
and the code's well documented, I don't need more verbosity.

> There's no reason that it can't be recorded in both places.

There's no reason it can't be recorded in fifty places.

That doesn't make doing so a good idea.

> If you looked at the commit message instead, you can get an explanation and
> the context of the change (meaning the other parts of the code that relied
> on the original change you're looking at).

You are describing looking at a commit, not the message. By definition the
code changes are not part of the commit _message_.

At the end of the day, what I described in my comment is something I arrived
at after years of writing verbose messages and slowly realizing it wasn't the
best way.

You are, of course, free to disagree. Do what works for you.

~~~
u801e
> Code review ought to catch comments that haven't been updated.

There are a lot of people who just look at the diff and not the rest of the
code when reviewing. If the comment doesn't appear in the context lines, they
may not catch it.

> if a change would have caused the comment to become stale and irrelevant to
> the project's current state, the commit message would have the same problem.

Not really. Unlike a comment that can be seen with the current code base, a
commit with an outdated message tends to show up in very few lines (if any) in
the git blame output for a particular file. For example, in a code base I deal
with, the first commit for a particular file where the message explained the
rational and some implementation details now only shows up in git blame output
for certain blank lines in the file since most of the file has changed in the
years since that commit was made.

> but it can still be a pain to figure out where code really originated from.

You may want to look into the -S and -G parameters of the git log command.
They can be used to see when some text was added, removed or moved.

> If the originating commit gives me a link back to the issue that started

Until you encounter the situation where those links are useless because the
system they linked to was migrated to a new platform. Had the actual text been
there, then it still would have been useful.

> the code's well documented

In my experience, code comments rarely explain why a change was made. But if
the associated commit message does contain that explanation, then it makes it
much easier to see the context of the change.

> There's no reason it can't be recorded in fifty places. > > That doesn't
> make doing so a good idea.

That also means you don't have to look in multiple places to find the
information you need. The further the documentation is removed from the code,
the more likely parts of it will be inaccurate due to changes in the code
base, so if you only record documentation in a contract or wiki, then it's
very likely that contract/wiki may not be completely accurate.

> You are describing looking at a commit, not the message. By definition the
> code changes are not part of the commit message.

You can see both by running git show sha1_from_git_blame.

> At the end of the day, what I described in my comment is something I arrived
> at after years of writing verbose messages and slowly realizing it wasn't
> the best way.

I've spent years encouraging people to write verbose commit messages for
changes they made. I've found them very useful (especially in cases where the
person who wrote them no longer works for the company and they're no longer
around to ask for further clarification). Whenever I come across a commit
message that doesn't explain why a change was made and have to ask the person
who made it what they were thinking, I invariably think that it would have
been much better if their explanation was in the commit message in the first
place.

~~~
NateEag
To clarify, I'm not arguing against commit message bodies entirely. They're
valuable and I write them regularly. Not for every change, but lots - maybe
sixty - eighty percent.

I'm just saying that huge, multi-paragraph essays are often a sign you're
putting information in the wrong place.

I should also add I'm a big believer in small, focused commits - I fairly
often will have a branch that has a few hundred lines changed and twenty
commits.

You make a good point about the issue tracker dying - I've worried about that
but have yet to encounter it in practice. Reducing the impact of such an event
is probably a good reason to denormalize a little there.

------
ronjouch
Meh. This post is not harmful, but focuses on syntax and fails to insist on
the most important thing: tell _WHY_ you made the change; the _what_ and _how_
are already apparent in your code.

See Greg Ward at PyCon 2014: _" Documenting history, or How to write great
commit messages"_. His talk starts at 6:07. Direct link:
[https://www.youtube.com/watch?v=Jb6ij4eRu6c#t=367](https://www.youtube.com/watch?v=Jb6ij4eRu6c#t=367)

~~~
joe8756438
This is exactly right. It's easy enough to see WHAT happened by looking at the
code. Of course you can document the WHY in code also, but that usually ends
up in a comment that gets out of date. Whether you're trying to figure out why
the shit hit the fan or understanding a new codebase: commit messages that
explain reasoning are gold.

------
jordigh
One thing I always want to tell people about commit messages:

There’s no length limit.

In fact, write as much as you can. Go crazy. Write some more. Explain. Talk
about how your day went. Tell us how you found the problem. Put benchmarks
that show why your change makes things faster. Show the stack trace or test
output that you’re fixing. Quote other people. Put an email chain in the
commit message.

In a well-curated commit history, commit messages become source-level
documentation available via an annotate/blame operation. Most people hate
writing documentation, but commit messages are about the only time when our
tools force us to write something. Take this opportunity to really write
something. It’s the only time when writing is really required in any way.
There’s no need for a length limit because most of the time the commit
messages are hidden away, and most interfaces will hide the full commit
message anyway (or can easily be configured to do so).

If you want practice jamming lots of information into a small amount of space,
that’s what the first line of the commit message is, but after that, don’t
feel constrained by length limits.

These are examples of my favourite kind of commits:

[https://www.mercurial-
scm.org/repo/hg/rev/4fb2bb61597c?style...](https://www.mercurial-
scm.org/repo/hg/rev/4fb2bb61597c?style=gitweb)

[https://www.mercurial-
scm.org/repo/hg/rev/ed5b25874d99](https://www.mercurial-
scm.org/repo/hg/rev/ed5b25874d99)

[https://www.mercurial-
scm.org/repo/hg/rev/1423ff45c322](https://www.mercurial-
scm.org/repo/hg/rev/1423ff45c322)

[https://www.mercurial-
scm.org/repo/hg/rev/dd028bca9221](https://www.mercurial-
scm.org/repo/hg/rev/dd028bca9221)

[https://www.mercurial-
scm.org/repo/hg/rev/8d5584d8345b](https://www.mercurial-
scm.org/repo/hg/rev/8d5584d8345b)

~~~
robocat
From your first link: I think that comment should be placed as a source code
comment near the source code: "preferedchunksize = 32768". I think magic
numbers should be described at the point they are defined, or at least put a
link (in a source code comment) to why the music number was chosen....

~~~
jordigh
That would be a lot of clutter.

When you're on a codebase where people bother writing commit messages,
reaching for blame/annotate output becomes second nature and reveals so much
about your code. It's just as good if not better than comments, because every
line in your source now has a comment.

~~~
tln
In fact, every line of your source has several comments! Which may or may not
really apply!

BOTH are needed IMHO, comments must be able to communicate knowledge a reader
of the code-as-a-whole needs to know, and commit messages must be able to
communicate knowledge a reviewer of the change needs to know.

------
tqkxzugoaupvwqr
Question: I use past tense instead of present tense because I explain what
changed. But I see a lot of commits written in present tense. Is one better
than the other? Which one?

~~~
laumars
You'll get plenty of devs who's make an impassioned argument that present
tense reads better (and they'd be right to an extent) but honestly it's really
more of an OCD thing than anything. The important thing is that messages are
detailed enough to be accurate but terse enough to be eyeballed quickly (if
you need more detail then include that after the first line summary); and that
you include reference numbers if you're commit is in relation to a ticket (eg
JIRA, Github Issues, etc).

Some people add tags, emoticons and other stuff. But the real key is
consistency. Pick a format and stick with it

~~~
brlewis
If the key is consistency, use present tense. If you consistently use past
tense, that works until your team merges with another one that's more
conventional.

The commit message is the headline of your story. Headlines are in present
tense even though they describe past events.

~~~
laumars
Honestly, out of all the things people argue about this has always struck me
the strangest. It's the part that makes the least real world difference (vs
not including ticket numbers - for example) yet it seems to be the thing
people get the most impassioned about.

Consistency is important, but if you're expending more energy arguing about it
than you would deciphering past tense message then you have serious questions
to ask yourself. :P

------
jph
Git commit message:
[https://github.com/joelparkerhenderson/git_commit_message](https://github.com/joelparkerhenderson/git_commit_message)

How to write better git commit messages, as a repo README. For example, we use
wording Add/Fix/Optimize/Refactor and semantic versioning, etc.

Git commit template:
[https://github.com/joelparkerhenderson/git_commit_template/b...](https://github.com/joelparkerhenderson/git_commit_template/blob/master/git_commit_template.txt)

You can use a template to improve git commit messages, that prompts for
writing "Why" you are making a change, and any co-authors, and any links, etc.

Constructive advice welcome. I'm the author.

------
vishnu_ks
If you enjoy this article you will find the Zulip project's commit guidelines
interesting as well :)

[https://zulip.readthedocs.io/en/latest/contributing/version-...](https://zulip.readthedocs.io/en/latest/contributing/version-
control.html)

------
MacroChip
This is something I put significant effort into. Same thing for test names.
Most importantly, I explain why I did something. A test name
"testFilterSpecialCharacters" adds no documentation.
"testFilterSpecialCharactersBecauseSpecialCharactersCrashTextBoxLibV1_3" is
way better. It adds documentation and context that don't exist in the lines of
code in the test. I also added the exact version of the library that motivated
the filtering for convince. Don't be afraid of long commit messages, test
names, or varibale names.

------
Memosyne
I've been using the commitizen prefixes
(feat/fix/docs/style/refactor/perf/test/chore) but I've noticed that they make
messages lengthier and a little more difficult to understand.

I really wish git would have a built-in category system so that I can
automatically generate changelog headings (features, tests, etc...) without
sacrificing the legibility of commit messages. Git clients could display this
information alongside the message (think of how Github displays the short
commit hash).

~~~
scrollaway
I have always been extremely peculiar about commit messages and IMO the
commitizen stuff (aka "semantic commits") is one of those things which is only
useful if you personally find it useful _and_ you are the only one working on
your project.

I have never seen it work in a team of 2+. People mix up what each prefix
means. Hell, I've seen someone "use" it but only ever use "feat:" even for
typo fixes. I ended up rewriting his entire git history to strip all "feat:"
instances from the commit message since they were just noise.

Basically the only time I've seen it work is when all the following is true:

\- You're on a solo project

\- You commit a lot

\- You're very consistent with your prefixing

\- You want to use those prefixes to generate changelogs.

… then it's useful. Otherwise, it's noise.

~~~
Outpox
I disagree, we've been using it with friends of mine and I enjoy it. The main
reason is so that's it's easier to generate a changelog as we're following the
Angular commit guideline. I would consider Angular a successful project and
this is their git history:
[https://github.com/angular/angular/commits/master](https://github.com/angular/angular/commits/master)

~~~
scrollaway
I mean, I've seen it used by larger teams as well. For example Sentry uses it.
I've also had feedback from several devs using it in such teams that the whole
thing was "bureaucratic bullshit".

That said if you and your friends are happy users of it, I'm glad. I suspect
that if you have a small team that knows each other well enough, that is a bit
of an extension of a one-person project and it can still remain. I personally
have seen the system crumble enough times with even one single user, not to
trust it in the hands of two at once.

~~~
Outpox
> I suspect that if you have a small team that knows each other well enough,
> that is a bit of an extension of a one-person project and it can still
> remain.

Well yeah that's exactly this. Tough I've got to admit that it doesn't work
that well as we'd like regarding external pull requests since contributors do
not all read our commit guidelines.

------
ncmncm
Imperative is certainly correct.

However, the examples fail by emphasizing what was changed, rather than why it
was changed. Sometimes those are the same, and that's ok. But when they're
not, why is overwhelmingly more important. What can be seen from looking at
the diff.

These days, why is most usefully a PR number, and your workflow automation
turns it into a URL you can click. I.e., why did you make a change not
motivated by a PR?

------
agumonkey
Having checked out a forgotten 3yo fork I realize how this could be ..
important.

~~~
adtac
That is also exactly what a new dev goes through, so one should remember that
it's not just for themselves.

~~~
agumonkey
The original project had generic commits .. harsh. Mine are just a tad too
cryptic. It's so damn easy to be fooled by everything you have in mind when
coding..

------
ttty
You should always put the Jira/story id in the merge commit at least.

~~~
dasmoth
This seems to have become really pervasive the last few years, and I recognise
it’s sometimes driven by regulatory/certification requirements. But in the
absence of those, what does this gain you over putting a sentence or three of
human-readable motivation into the commit message?

~~~
detaro
All the context from the issue that doesn't fit in a sentence or three?. Of
course it depends, if the issue doesn't have context it's not important, but
things like "who requested/reported this", "who was involved in decisions
made", "what alternatives were considered and why where they rejected" might
not necessarily fit in the commit message but exist in an issue.

~~~
dasmoth
If there's stuff that's valuable, I'd prefer to see it pasted into the commit
message -- far less likely for links to get broken.

If it's _long term_ valuable, _i.e._ "I considered obvious, attractive
alternative algorithm X but it failed horribly because of Y", I'd prefer that
to go in a comment in the code instead. Far more likely to still be noticed in
three years time, after the code's been run through two different auto-
formatters and otherwise mangled around.

------
buttholesurfer
We started using commitizen at my workplace. It really seems to push the idea
of good commit logs. Combined with jira ID hooks to keep people from pushing
without a story/ticket.

[https://www.npmjs.com/package/commitizen](https://www.npmjs.com/package/commitizen)

Edit: doh, didn't scroll to the bottom!

------
seymour333
I always appreciate commit messages that are informative and well structured.
That said, I'm not a fan of specific formats for commits. The commit messages
in a project are where a lot of that project's collective "personality" is
stored. If you look through the commits for a project with a "colorful"
variety of messages, you'll get a sense not only of the work that was done,
but of the people who helped create the project.

Somewhat related: @git_commit_m on twitter has some great (and amusing!)
examples of what not to use for commit messages, which are pulled from
github's public data set.

------
kureikain
The key to write a good commit message is to write it for others, not for you.
Many time I see commit message is written for the author itself who has all
the context around it.

The Go programming language has very good commit messages

------
TuringNYC
For me, an ideal git commit message is one that also links to a bug or feature
ticket. Both {Github+Github Issues} and {BitBucket + Jira} support this almost
seamlessly, I imagine other systems do as well.

~~~
IE6
I agree here. OP's article mentions Chris Beam's page [1] and I have all our
developers follow that structure which helps but ultimately the biggest
strength is the final line with the link to our JIRA.

[1] [https://chris.beams.io/posts/git-
commit/](https://chris.beams.io/posts/git-commit/)

------
iliaznk
There's this advice I read in a similar article that, I think, makes a lot of
sense and is ignored in 99 cases out of 100 – put a period in the end of a
commit message so a reader can clearly see that nothing is broken or corrupted
and what they see is the entire message in its full.

Each of the few times I would mention this requirement on a project people
would look at me like I'm a retarded child and keep not using the period.

------
pasxizeis
Relevant: [https://github.com/agis/git-style-
guide](https://github.com/agis/git-style-guide)

------
stefan_
There are some tools that basically don't support this. GitLab is the biggest
offender:

1) default view is all commits in a MR squashed together

2) messages beyond the title hidden under a click on some micro expand icon

3) going through a MR commit by commit means clicking on an individual commit,
waiting for the damn thing to load it's view for 10 seconds, then when you're
done you have to go backwards and do it all again

~~~
dcosson
We use the same settings in Github of squashing PR commits. I guess it's a
matter of preference but IMO this workflow is a better version of what the
article describes.

You get the best of both worlds, you end up with a very readable history of
commit messages, where each one describes a single feature or unit. But while
you're working you don't have to break your flow to write documentation every
time you commit, or go back later to rearrange/rebase commits.

------
skinnyasianboi
I will redirect the article to my boss and coworkers who are not conviced to
commit with "Fix/Add/Update".

~~~
Vinnl
My favourite anecdote about this is an old coworker of mine who, at a certain
point in time, had a number of successive commits with the commit message
being his first name.

~~~
rocqua
I mean, if he's called Peter, and 'to Peter' has come to mean something like
'fix tiny typos' then a commit that says 'Peter' kind of makes sense.

------
Doches
I'm a big fan of outsourcing this sort of discipline to tools -- check out
[Komet]([https://github.com/zorgiepoo/Komet](https://github.com/zorgiepoo/Komet))
for a commit-specific text editor that makes it easy to write better commit
messages.

------
kazinator
Write commit messages in the GNU ChangeLog format.

E.g.

[http://www.kylheku.com/cgit/txr/commit/?id=bfc527af1af619742...](http://www.kylheku.com/cgit/txr/commit/?id=bfc527af1af619742163d238eac9f2b24f363b0d)

------
stroebjo
I would recommend to also look at this guideline + tooling to create an
automatic changelog based on your commits:
[https://www.conventionalcommits.org/](https://www.conventionalcommits.org/)

~~~
shouldnt_be
I always force myself to write good commit message. But I often ask myself if
it is really useful or if I'm just too tight and want things to look good.

This standard might be useful for library maintainers in the cases stated
here: [https://www.conventionalcommits.org/en/v1.0.0-beta.2/#why-
us...](https://www.conventionalcommits.org/en/v1.0.0-beta.2/#why-use-
conventional-commits)

Like having everyone using the same guidelines (code style) when writing code.
This might also be useful if everyone use it.

------
z3t4
I want to know _why_. I can already see what you did by looking at the diff.

~~~
jstimpfle
When you need an overview what happened in the last week, do you prefer to
_always restrict yourself_ to scanning 10k lines of diff (which may be missing
relevant context)? Wouldn't a screenful of short commit log be helpful?

------
Brosper
We use commitizen and it's working well. We also autogenerate CHANGELOG.md

------
gcoda
"if applied, this commit will" Works like code comments, and i feel how it
helps daily when using gitlens vscode plugin.

------
chatmasta
I'm obsessed with writing good commit messages, for a few reasons.

(1) Documentation is important, and comes in a few major forms: docs, code
comments, commits, and tests. Docs and code comments are good for initial,
high level understanding. Most "bad" documentation appears in the form of code
comments and external docs, because they are most likely to drift out of date
with the code. Tests do not have this problem (assuming they all pass) because
they are in sync with the code, and provide a nice way to understand
interfaces and implementations (the "what"). Similarly, commit messages, by
their very nature, cannot drift out of date with the code, and provide an
opportunity to document the "why". Therefore, commit messages are at least as
important as tests, comments, and docs and should be treated with the same
respect.

(2) Often the "why" of a particular implementation touches multiple files
around the codebase; in many cases you want to document the "why" in comments,
but that only helps when it applies to a single section of code. A commit
message is an opportunity to document the "why" of an implementation that
touches multiple parts of a codebase.

(3) Writing good commit messages forces you to keep the code contents of a
commit tightly related to its message, lest the message be inaccurate.

(4) Because good commits are groups of closely related files, you can
understand the subtle interactions of a codebase by looking at which files
change in the same commit.

(5) A good commit log tells a story and can often provide reasoning behind
what may seem like the madness of a legacy codebase. If you don't understand
why a file does what it does, just search the history for all commits to that
file and you will have a much better idea. There is a cool tool called Gource
[0] which visualizes commits to a git repo in a way that can tell such a
"story."

Some of the rules I follow:

(A) A short message with an imperative mood documents the "what". A longer
body, in list form, documents the "why" and/or the "how." Always include the
body unless its a tiny commit with an obvious why/how.

(B) A pull request should follow the same idea as commits, in that it
documents the how/why. It should also document the "how" of using any new
features it introduces. If possible, it should include
screenshots/videos/links of the changes so QA engineers / managers can quickly
read it for high level expectations of the next release. Other commenters in
this thread have mentioned that pull requests are where the documenting should
happen. But good pull requests are just as important as good commit messages;
they are not mutually exclusive. A pull request is just a higher level commit.

(C) Before submitting a pull request, use `git rebase -i` against the
development/master branch to squash, reorder and fixup commits. For example,
sometimes one commit is "solve problem A using method X," but you change your
mind in a subsequent commit "actually, solve problem A using method Y". In
that case, the two commits should be squashed together if they are in the same
pull request. In general, do not be afraid to aggressively reorder and regroup
commits in a pull request, if it improves clarity of the pull request as a
whole. For this, I like to use a tool called rebase-editor [1] that makes
interactive rebasing easy and satisfying.

[0] [https://gource.io/](https://gource.io/)

[1] [https://github.com/sjurba/rebase-
editor](https://github.com/sjurba/rebase-editor)

------
arrty88
Does merging / squashing kill good commit message?

------
ft_TI-84
Definitely works better than " "

~~~
cpburns2009
I frequently use "." because my commits are all over the place. I know it's a
bad habit.

------
0xdeadbeefbabe
Quit overloading the word good.

------
InGodsName
When i Opensource project, i hire freelancers to beautify my commit messages.

It makes all commit messages sound like a story where one innovation leads to
another.

~~~
bauerd
Surely this is a joke? You hire someone to clean up your commit messages?

~~~
InGodsName
No it's not a joke. Aesthetics matter.

Look at my latest comment, it's part of the package.

------
dzolvd
tl;dr: git gud

------
StapleHorse
Haaaaands!!

------
glutamate
Disagree. This is creating barriers for people to commit early and commit
often.

~~~
mikelward
You shouldn't be merging broken/exploratory stuff to master. Rebase or rewrite
the commit so it's correct, self-contained, and others can understand it.

------
muratgozel
The content of commits should be like Medium articles. I give up when I see it
in the command line.

------
TbobbyZ
What's the point of adding a sentence or two to a commit message? I only
include a keyword and the issue number, e.g. "Closed #41" or "Fixed #41". This
will link the commit to the GitHub issue, which will allow any users to see
all the details they need about what was involved in the commit message.

~~~
rco8786
That’s not particularly helpful if you’re looking back through git logs or at
a git blame. Unless you’ve memorized the context of every github issue you
have.

Also what if you move from github to bitbucket? Or self hosted git?

Git provides a great way to keep your changelogs directly next to the code,
why not use it?

------
chvid
One of the many horrible things about git is that it barks at an empty commit
message.

Of all the documentation that whatever you are working is lacking; you want to
have people writing commit messages.

Seriously; no-one reads this stream of incoherent babble. If you want more
documentation start somewhere else, somewhere where your documentation effort
actually would be useful.

~~~
majikandy
I can’t believe this has been greyed out. Absolutely well said. Self
documenting code all the way, what a ridiculous place to hide documentation.

~~~
chvid
Of course I was joking.

All IT-projects need more documentation. And all tools should enforce that.

Git should require a readme.md file all repositories and that file should not
allowed to be empty.

Java should require javadocs for all methods, fields and classes. Should not
compile if missing or empty.

And so on ...

------
amelius
Or integrate with an issue tracker and/or project management tool, and you'll
get:

    
    
        43ec6aa Fix issue 1001
        4fe84ab Fix issue 1002
        753aa05 Implement feature request 1003
        df3a662 Implement spec 1004

~~~
k_
I'd say _add_ issue tracker reference, not replace the description with it

    
    
        43ec6aa Fix error when the URL is not reachable (#1001)
        4fe84ab Add error message if something went wrong (#1002)
        753aa05 Add server fingerprint check (#1003)
        df3a662 Fix shadow box closing problem (#1004)

~~~
deadbunny
Yup, though I usually put the ticket number in the body of the commit rather
than the title.

~~~
adtac
Me too, but I put a full hyperlink to the github/gitlab issue in the body
instead of just the number so that someone can just click and start reading
what it's about. It also creates a back-reference on the issue page in some
web-based issue trackers like Github.

