
My Favourite Git Commit - robin_reala
https://fatbusinessman.com/2019/my-favourite-git-commit
======
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.

~~~
webscalist
Every commit message must start with JIRA ticket number

~~~
sixstringtheory
I work at a place that used to prescribe this. I dislike it because it adds
too much repetitive noise to the abridged git log. (It occurs to me that you
may be making this point in a tongue-in-cheek way.)

Originally I suggested we put the JIRA number/link in the commit body, but
then I learned about git-notes to add metadata to commits and now I kinda want
to do this with the semantic labels suggested by the thread OP, too (I
currently use the schema suggested at
[https://seesparkbox.com/foundry/semantic_commit_messages](https://seesparkbox.com/foundry/semantic_commit_messages)).

~~~
masklinn
Notes kinda bloat the repository with additional objects, and they can be
removed independent from the commits, so I'm a bit iffy on using them for
this.

~~~
sixstringtheory
Good points to consider, thanks! It’s good to know all the tradeoffs.

------
jordigh
I really appreciate this kind of commit message. There’s some very good ones
in the Mercurial logs too:

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

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

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

[https://www.mercurial-
scm.org/repo/hg/rev/4a0d0616c47d](https://www.mercurial-
scm.org/repo/hg/rev/4a0d0616c47d) (all modesty aside)

Long commit messages aren’t that atypical. Have a stroll through the logs:

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

Mercurial inherited this style of commit messages from Linux email-based code
review (the Mercurial originator was a kernel hacker), because in that
workflow your commit messages are kind of a persuasive essay for why your
commit should be accepted. I believe that writing commit messages with that
kind of goal in mind, thinking “why should you take this commit?” is a good
motivator for writing something good and useful.

------
beefhash
I think my favorite (in terms of humor) is a commit from mpv complaining about
locales and encodings. You can practically _feel_ the committer's sheer
frustration.

[1] [https://github.com/mpv-
player/mpv/commit/1e70e82baa9193f6f02...](https://github.com/mpv-
player/mpv/commit/1e70e82baa9193f6f027338b0fab0f5078971fbe)

~~~
mikehollinger
My favorite (in terms of dark humor, if we’re honest) is YOLO, one of the more
interesting deep learning object detectors. [1] It is the exact opposite of
yours in every way. The code is brilliant however.

Even the papers are snarky. [2]

[1]
[https://github.com/pjreddie/darknet/commits/master](https://github.com/pjreddie/darknet/commits/master)

[2]
[https://arxiv.org/pdf/1804.02767.pdf](https://arxiv.org/pdf/1804.02767.pdf)

~~~
SamBam
I was reading it and kind of interested, and thought this line was funny:

> I have a lot of hope that most of the people using computer vision are just
> doing happy, good stuff with it, like [...] tracking their cat as it wanders
> around their house

And then suddenly realized I've wanted to do _exactly that_ for a long time.
Well... specifically install a camera that can detect my cat on the counter
(and not my hands doing stuff) and sound an alarm/puff air to get him off.

Could this work for that? I think it could! I know my winter project...

~~~
camochameleon
On the topic of cats vs automation, I'd recommend reading this post [1]
describing the arms race created by the writer's cat attempting to break into
an automated feeding machine. HN discussion here [2]

[1]
[http://quinndunki.com/blondihacks/?p=3023](http://quinndunki.com/blondihacks/?p=3023)
[2]
[https://news.ycombinator.com/item?id=13230904](https://news.ycombinator.com/item?id=13230904)

~~~
SamBam
We had an automated feeder with two chambers, each held down by a rotating,
ticking timer switch. You rotate the switch to, say, 12 hours in the future,
and 12 hours later the slot lines up and the lid pops over.

After many months, my cat learned to stand on top of the lid and use both paws
to rotate the switch forward until the lid popped open.

This blew my mind. The switch was separated from the lid. I could imagine the
cat attacking the lid itself, but this separate mechanism, requiring a motion
completely distinct from the motion of an opening lid, and requiring patience
without instantaneous reward or even evidence that it was going to work.... I
just couldn't believe it.

~~~
jstarfish
Never underestimate captive animals (or humans). They have nothing but time to
observe your patterns of behavior and learn from them...

------
messe
For anybody wondering, the likely origin of the invalid character is somebody
using an Apple Ireland/UK keyboard layout where # is Option-3 (AltGr-3), and
non-breaking space is Option-Space (AltGr-Space).

~~~
laurent123456
I don't know how many times these non-breaking spaces caused problems. I think
linters should prevent commits that contain non-breaking spaces. And if really
one is needed, it should be encoded as `&nbsp;` or with whatever encoding is
relevant.

~~~
robin_reala
…or fix the non-Unicode compatible systems that are consuming the commit
messages and breaking? If they fail with an nbsp then they’re probably also
going to fail with more obviously useful non-ASCII characters.

~~~
laurent123456
How often are non-breaking spaces purposely inserted vs accidentally? And the
tools might handle them fine but will produce strange results or errors. An
example is inserting a non-breaking space in a document or string. It will
prevent word wrap, which might not have been the user intent. A linter that
requires these spaces to be explicitly set in encoded form would avoid these
issues.

~~~
supergarfield
Non-breaking spaces are required to typeset French correctly, at least:
[https://en.wikipedia.org/wiki/Question_mark#Stylistic_varian...](https://en.wikipedia.org/wiki/Question_mark#Stylistic_variants).
The accidental insertion of non-breaking spaces is a possible issue, and it's
a bit harder to detect than other typos, but it's also probably not as bad as
other typos. Overall I think it's a bit hard to make the case that they should
be disallowed.

------
deaps
This gives me ideas.

My commits are usually short and sweet - to the point. I document my code very
well, however.

One of my strengths in a _previous life_ as a Master Automobile Technician was
the ability to document the entire process -- from duplication of a concern,
to troubleshooting, to correction, to verification...it's literally how I got
paid (which I never understood why so many automotive techs took short cuts
while documenting, especially for warranty concerns where you deserve to be
paid (by the manufacturer) for everything you did that was necessary to fix
the concern the first time).

I could be mistaken (life-long coder, former network engineer / architect for
nearly a decade, but I'm currently in my first-ever role as an actual backend
developer). I think I was told to keep commits to one line unless _absolutely_
necessary. I'll have to bring this up though. I like the idea of searching
through the git logs for specifics, as opposed to having outlook search
through the git commits for actual pieces of code changed, or error codes
which might not actually be there.

In either event, at least more descriptive, yet still short, messages such as
what strictfp suggested _" Replace invalid ASCII char. Fixes rake error
'invalid byte sequence in US-ASCII"_ Although I really like having some
reasoning and logic - or how/why in those easily-searchable logs as well.

I think some people remember _everything_ and some people don't (although
we're all probably _roughly_ similar logically). I have a hard time
remembering what I ate for lunch yesterday - that's why I count on good
documentation to function as efficiently as possible in the future. I've
worked with people who have an absolute uncanny ability to remember 'stuff'.
That's impressive, but I do not have that ability myself.

~~~
luhn
> I think I was told to keep commits to one line unless absolutely necessary.

The advice I've heard: Your first line should be a concise summary of the
commit. This is because a lot of UIs only show the first line up front.
(GitHub, git log --pretty=oneline, etc.) However, it's okay (and often
encouraged) to go into further detail on subsequent lines.

------
tomashubelbauer
I do feel like Git commit descriptions are severely under-utilised for sure,
but I believe there is a reason for that which until fixed, will prevent rich
and contentful commit descriptions for flourishing.

In the article order: the screenshot is from a commit detail page. How often
do you land on this page? You need to specifically click through. If you are
in a commit list, the only thing that sets title-only commits and commits with
description apart is an ellipsis link which practically blends in with the
background. It is not very well integrated nor discoverable. Also I don't
believe the commit descriptions render as MarkDown (unlike issues) which is
also a shame as it feels like less a doc then. But I might be wrong on this.
But even outside of GitHub, how many other UI/IDE plugins and other kinds of
Git tools restrict commit display to just the title and put the description on
the sideline? Most of them. I think this further leads to the currently low
value of the commit message being searchable. Since it is exceedingly rare for
good commit messages to exist, no one thinks to search them. People default to
Google, when their own project's codebase/knowledge base could hold the answer
to their query. I don't have much of an opinion on the commit message telling
a story / having a human touch. I mean, it doesn't hurt I guess, but until
_full_ commit messages become more "mainstream" (for a lack of a better word),
they can be as human as they can, but they will live in solitude.

~~~
Darkstryder
In the same vein, I wish there would be a standard workflow for putting code
_inside_ commit logs.

The typical use case would be database migration scripts : IMO they are always
a pain to version properly because fundamentally Git and all the other
software versioning tools let you describe the "nodes" (in the graph theory
sense of the word) of a codebase ("at commit A the code was in this state, at
commit B it was in the other state"), but severely lack when it comes to
describe the edges between nodes ("in order to go from state A to state B, you
need to execute this code")

I think the temporal dimension of software engineering is still poorly
understood, and severely undertooled.

~~~
codegladiator
> when it comes to describe the edges between nodes ("in order to go from
> state A to state B, you need to execute this code")

Isn't that what a patch file gives ?

~~~
Darkstryder
Sometimes no. For instance a database migration script is not equivalent to
the diff between two database creation scripts.

While it should be possible to take a database creation script (state A) and a
database migration script (edge A->B) and infer the new resulting database
creation script (state B), the reverse is not true.

This is the tables vs events duality described in this great article :
[https://engineering.linkedin.com/distributed-systems/log-
wha...](https://engineering.linkedin.com/distributed-systems/log-what-every-
software-engineer-should-know-about-real-time-datas-unifying)

------
strictfp
OR you could just write

Replace invalid ASCII char. Fixes rake error 'invalid byte sequence in US-
ASCII'.

I don't want your entire life story in my commit log.

~~~
leejo
> I don't want your entire life story in my commit log.

I[1] want enough debug information in the commit log to be able to reproduce
the issue without having to go on web hunts to understand the problem.
Especially when the change appears to be trivial on the surface, because these
are the ones that can turn out to be rabbit holes.

I don't want to have to interrupt you to get this information because you
didn't write a good enough commit message, and you probably don't remember
anyway. I don't want go look at an external issue tracker that i may not have
access to, or may not even exist anymore.

[1] Where "I" is: me, your future self, a future maintainer, a junior dev, an
open source contributor.

~~~
afiori
> I don't want go look at an external issue tracker

Related question: are there projects that use git itself as issue tracker?

~~~
cipherboy
Pagure [0], Fedora's git forge, hosts code, issues, docs, and pull requests as
four separate git repositories under the hood [1]. However, only project
administrators can clone most of those repos.

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

[1]:
[https://docs.pagure.org/pagure/usage.html](https://docs.pagure.org/pagure/usage.html)

------
withinboredom
One of my favorite pranks is to put control characters in the commit message
(like the bell) and then you get an auditory notification anytime anyone
nearby opens your commit messages.

~~~
govg
Does this actually work on modern editors / browsers?

~~~
messe
Only in the terminal. That said, the first thing I put in my .xsession is
`xset -b` to disable the audible bell.

------
segfaultbuserr
Also, if you haven't seen it before, read the Linux kernel Changelog. The
latest Changelog can be found at [0]. Almost every commit tells a story,
unless it's a trivial fix. If there's a bug, it often contains detailed
analysis and rationals, and it's a form of important documentation.

Although it's not always practical to follow them in personal/work projects -
Linux commits are the results of multiple rounds of reviews, and the commit
log is its justification - but in personal/work projects, commits are made in
real-time as soon as you debugged/refactored something. But I still use Linux
kernel as a guideline for my own commit log, at least for new features or
bugfixes.

[0]
[https://cdn.kernel.org/pub/linux/kernel/v5.x/ChangeLog-5.3.7](https://cdn.kernel.org/pub/linux/kernel/v5.x/ChangeLog-5.3.7)

------
vortico
I was working with a research team at UCLA and we used Wolfram Mathematica to
process our results.

In Mathematica, pretty much any object can be a variable name. You can drag a
JPEG of Kim Jong-un into Mathematica and integrate an expression with respect
to Kim Jong-un. We'd sometimes get a kick out of that.

Near the end of the program, our whole team needed to process the last 3
months of results, but we were all getting consistently incorrect factors off
when running our Mathematica notebooks. Five hours later someone discovered
that one of the variables contained a stray Unicode whitespace or null
character (or maybe a non-Unicode blank Mathematica object, such as a Graphics
object with 0 area) that someone must have accidentally spawned somehow before
saving and distributed the notebook to the rest of the team. Since Mathematica
didn't recognize it as spacing but as part of the variable name, making it a
different variable, the result of our integrals were incorrect. E.g. the
integral of x^2 is x^3/3, but the integral of x _x ' is x^2_x'/2, so the
multiplier would be off by a factor of 3/2.

After discovering and selecting it, we "cut" it into the clipboard, pasted it
into another Mathematica notebook, saved it, and it was never opened again.

------
drej
This reminds of a Markdown issue I've had many many many times - sometimes
(and only in some engines), headings would not render and I'd only get '#
foobar' instead of '<hx>...'

It took too long for me to track the issue. When I write '#' using alt-3, I
then write a space and oftentimes I don't lift alt soon enough and alt-space
creates a non-breaking space (on macOS). And some/most Markdown engines don't
recognise '#nbsp;text' as a heading.

I suspect something like this happened in the commit linked here.

~~~
misnome
This happened to me all the time, especially with python2 code without
encoding declared (which caused a failure to parse the file because of the
comment).

I’ve since switched my editors to highlight such characters.

~~~
jsjw7sbw
Happened to me on linux all the time when writing the pipe operator in a
terminal. Thankfully the error message lead me to a fix.

------
drej
I love these commits. Then don't have to be this verbose, but they have to
tell a story of _why_ things were done. I can sort of deduce the _what_ from
the code itself, but the _why_ is sometimes shrouded in mystery.

I started with these explanatory git commits a few months ago and they are
super useful, even if you're just reading your own commits from some time ago.

~~~
tigershark
To me they are red flags because it means that very likely who writes this
kind of commit messages doesn’t use a proper issue tracking system.

~~~
dijksterhuis
To me its beautiful, because it does what an issue tracking system does not
do: it explains everything. Who, why, how, what, when. It is beautiful and
simple documentation.

Issue tracking typically revolves about the who, what, when - not why it
happened, or how it was resolved.

This is why I believe that code can never be fully self-documenting. I can't
understand _why_ the code exists from reading it. All the floofy contextual
stuff is missing, and commits like this help to explain the floofiness.

~~~
tigershark
I think that you are not using properly the issue tracker. You absolutely need
as a bare minimum the why and the reporter of the issue. When you do a blame
you can easily see the issue id and open it with 1 click to understand why
that code exists and who requested the change.

~~~
dijksterhuis
But now I have to go find the issue in a completely separate system, rather
than just look at the commit message.

It’s added complexity, which is something we strive to remove from our code.

------
gwbas1c
Honestly, I think better rules are:

\- Whenever someone asks a question in a pull request, answer it by putting a
comment in code. \- Include a ticket number (for whatever ticketing system you
use) in the commit

Why? I find that commit messages are black boxes. They only come out when
doing a git blame, but they don't show up in my IDE. Instead, I'm more likely
to run across messages like this when they're comments in code or discussions
in our ticketing system.

I think if we had tighter integration among our IDE, git, and the ticketing
system, detailed messages commit messages like this would be extremely useful.

~~~
adwww
Code comments have a habbit of getting lost during future tidy ups or
refactors.

If the code is that unclear it needs a comment, refactor it into a named
method, where the method name describes exactly what it's doing.

------
sethammons
I'm glad my near-exact pain has been experienced by others. I had an undefined
function call of ' ' in a ruby script years ago. Finally, I turned to a hex
editor at the suggestion of a colleague. The culprit was non-ascii whitespace
that ruby decided should be a function declaration. Copy pasta error out of a
hipchat code snippet.

~~~
Dumblydorr
Sorry, beginner here, can you explain more simply the difference in the
whitespaces? Are they just encoded differently?

~~~
sethammons
There are full on character encoding introductions. I think an easy to
approach one is:

[https://www.joelonsoftware.com/2003/10/08/the-absolute-
minim...](https://www.joelonsoftware.com/2003/10/08/the-absolute-minimum-
every-software-developer-absolutely-positively-must-know-about-unicode-and-
character-sets-no-excuses/)

Basically, ascii is encoded as integers. '32' represents a space. However,
ascii is quite limited and if you want non-US-centric characters, you need to
use other character sets. For a myriad of reasons, once you go into unicode
(the Universal Character Set) there are lots more options for characters. For
example, there are multiple whitespace characters.

[http://jkorpela.fi/chars/spaces.html](http://jkorpela.fi/chars/spaces.html)

These exist to give different widths or other adjustments to text that is non-
ascii. What likely happened in the post (and what did happen to me) is copy-
pasting from some document that changed a normal ascii space (that Ruby would
expect and know how to deal with) into a unicode character that Ruby
interprets as any other character. It would be like having a stray 'g' in the
line, but you, as a developer, don't see it. Fun :)

~~~
schoen
This explanation of where the non-breaking space came from feels really
likely:
[https://news.ycombinator.com/item?id=21290159](https://news.ycombinator.com/item?id=21290159)

------
katzgrau
I'm always intrigued when developers complain that it was "[surprisingly short
amount of time] of my life I won't get back."

Maybe I'm not as clever, but I'm lucky if I fix an issue like that within a
few hours. It can sometimes derail a workday. In fact, fixing in a few hours
would be something worth celebrating!

~~~
Pxtl
Seriously. I'd count my lucky stars if I squished that one in under 4.

------
Zenst
When reading code, you want somthing simple and to the point most of the time
(if that). Yes, it's nice to be able to tunnel down into the details - but
this was fixing a bug, the code should just have a short description and more
so - the reference number of the bug and if you need to, you can look that up
on your bug tracking solution and get that detail.

Big problem with detailed comments, things change and comments (like code) can
become obsolete/redundant and not reflect the code as the code got updated,
but the ocmment did not.

No solid solution really and gets down to preference and also mindfulness of
the life of code/comments.

Would be great to have code that you could rightclick and get the
documentation, some woudl even prefer being able to write documentation and
that gets turned into code, others would love code that could could be
autodocumented. Get's down to taste, preferences and more so, experience. See,
every programmer over time will eventually encounter a situation on somebody
else's code that they are maintaining, fixing or replacing and find that the
comments do not reflect the code. You eventually get down to the stage that
you almost actively ignore comments based upon such experiences.

So whilst a detailed description in the form of a comment is good, it can and
should be elsewhere, either the initial spec and program documentation or in
this instance - bug tracking software system and just simple short line with
bug reference or indeed just bug reference.

------
stockkid
Contrary to the author's point, I don't think a git commit becomes more
beneficial to the readers by adding a human context.

Building "compassion and trust" actually distracts readers from the essence of
the commit: what happened and why. I am not discarding the importance of human
element in collaborative endeavors but maybe such area should be pursued
outside of a version control system.

------
danmur
I wish Git wasn't like some generic term for source control. A little
diversity is good!

~~~
BlueTemplar
Good point - but what is the use case where another source control system
(like SVN?) works better ?

~~~
NoGravitas
There's not really any case where another source control system works _better_
, but lots of cases where they work just as well.

Mercurial, for example, is functionally identical to git, but some people
prefer its interface.

For a highly centralized organization where people only ever work on the
organization's intranet, a centralized source-control system like SVN works
well enough, and may have some advantages for the organization.

~~~
BlueTemplar
Actually, I found one just by reading this thread : Fossil has integrated Bug
Tracking, Wiki, Forum, and Technotes. Which is great since I would prefer not
having to worry about backing up these in the first place ! (Then git also has
git-bug for at least some of this functionality...)

------
iovrthoughtthis
This is my favourite way to write commit messages. Like a blog post on the
thing I’m doing.

I wish it were easier to gather, annotate and contextualise (perhaps with
images) the contents of a commit message.

------
simonh
My favourite Github commit was someone removing their password from a test
list in a penetration testing tool, because they didn't want anyone to know
their password. I just tried, but couldn't track it down. The subsequent
comment trail was hilarious.

~~~
mpettitt
At a guess,
[https://github.com/danielmiessler/SecLists/pull/155](https://github.com/danielmiessler/SecLists/pull/155)
?

~~~
olucode
This is the best PR thread on the internet. Thank you for sharing this.

------
Fnoord
> It makes everyone a little smarter

> One thing Dan did here that I really appreciate was to document the commands
> he ran at each stage. This can be a great lightweight way to spread
> knowledge around a team. By reading this commit message, someone can learn
> quite a few useful tips about the Unix toolset:

> [..]

In the spirit of making everyone smarter: simplicity matters. Using the
combination of find -print0 and piping that to xargs -0 is much easier than
the mentioned abacadabra of characters.

From the xargs(1) manual:

> The options are as follows:

> -0 Change xargs to expect NUL (``\0'') characters as separators, > instead
> of spaces and newlines. This is expected to be used in > concert with the
> -print0 function in find(1).

------
sytelus
I don't like all these information shoved in to commit logs. This should have
been filed as issue and then linked to the commit. The issues are much more
searchable, readable, commentable, archivable and interactable in many
different ways.

------
deividy
I figure that so few people read commit messages that in most part of time
this is kind of useless. Specially in an early stage of a project. Things will
change as faster as I can type a message such as this.

Code is simple. Humans overthink. I would prefer a commit message such as:
"Fix invalid byte sequence in US-ASCII when running bundle exec rspec." than a
dev that keep stucked trying to write a cool message and never fix the issue.

~~~
avian
> few people read commit messages

That very much varies. In a project where 90% of commits are “fix”, “foo”,
“commit”, etc. then yes. Nobody will ever read that (or do pretty much
anything else useful with a VCS).

On the other hand, when every commit message is on the level, the yes, people
do read them. Actually, first step when investigating any problem or trying to
understand some code is to look at the commit log.

See e.g. Linux kernel or some of the Google-related open source projects
(chromium, webrtc, etc.) for examples of good, long-form commit messages.

------
residentfoam
In a professional context (and not only), one would think that this should be
the normal expected good practice. But unfortunately, that is not the case.

It is so surprising (well not really) to see how, in most cases, developers
put so little to close to zero effort in writing proper commit messages and
more in general to have a clean commit history. They simply don't care and you
keep seeing garbage commits with non-sense to close to empty message and
description. Sadly enough this is seen as normal and just accepted.

Every single team I have been working with from small to large organizations I
always had to pick up on the "write proper commit history" fight. And even
after extensive explanations on why you should do that, people simply don't
care and they keep pushing stuff like: "fix", "updated class z" and stuff like
that.

Commit history does not seem to be part of the review process.

Sometimes it is just so depressing to see how so unprofessional software
engineers are.

~~~
ImaCake
If it makes you feel better, biologists are often no better. Our equivalent to
git commits is labelling tubes and keeping little excel databases of what has
gone where. Often databases stop being updated or people give their tubes
esoteric labels that are meaningless to those who look at them a year later.
As a research assistant in a large lab, I discovered blood tubes with
literally no labelling, and often spent hours searching for samples in the
labyrinth of freezers in that lab. It is also not uncommon for papers to be
retracted because the original authors lost the raw data!

------
Myrmornis
In an organization I've worked at we used to write good commit messages, about
9 years ago, before we started using Github. Then our good commit messages
turned into good PR intros. I think Github and Gitlab etc are fantastic, but
I'm a little sad that so much valuable information has been divorced from the
git repository itself (and of course, the ultimate fate of those PR intros
across the open source world depends on the companies hosting the repo.)

Personally, rightly or wrongly, the fact that I can't use Github/Gitlab to
contribute to Django and Emacs prevents me from trying to make contributions
to those projects. Similarly I find the insistence on using email to send
patches, frustrating, when I know PRs (MRs) work so well. However, I guess
Emacs and the linux kernel are keeping their good commit messages in their git
repo and not losing them to a hosting company.

Maybe there should be tooling for automatically converting a PR intro to a
commit message.

------
CharlesColeman
I really like this commit message. I've found that switching to git from more
traditional version control systems requires a lot more discipline in some
ways. A lot of people just commit, commit, commit lots of incremental changes
with no context or story to them. I've seen pull requests with _dozens_ of
tiny commits together make up a cohesive effort, but individually are just
useless. I've been really having to push my team to spend time to cleaning up
their commit history before getting their pull requests merged.

I think it's really important to capture the context and indent behind
changes. I may be weird, but when I'm fixing an issue, often try to find when
it was introduced, which often provides really useful information for the fix.
That's much harder to do if the commits aren't cohesive and the messages
aren't descriptive.

~~~
generaljelly
I'm one of those people. I make lots of little commits, it gives me space to
really make a mess of coding going down some rabbit hole and performing 'reset
--hard' when I get too away from myself, and track what I'm doing locally. As
long as each commit isn't causing a problem with CI/CD, and my pull request to
master is well documented what is the value added of cleaning up commits?

(Junior developer here, looking to be convinced!)

~~~
adwww
Depends how you handle your PRs. If you squash and rebase within Github or
similar, no problem.

But ideally interactive rebase before you push your PR and tidy up all those
commits into larger topical ones.

Eg.

"DEV-1 - Write tests for widget X calculator" "DEV-1 - Implement widget X
calculator" "DEV-1 - Refactor widget X factory service"

------
pololee
> I like Git commit messages. Used well, I think they’re one of the most
> powerful tools available to document a codebase over its lifetime. 1000000%
> agree!

One of my co-workers in my previous job, I miss reading his PR and git
message. It's such a joy reading his PR. I still remember reading his PR on
introducing Babel to our big, old Rails 4 app before webpacker, Ruby Babel
Transpiler came to life. It's like taking a journey with him. You can see his
smile, struggle, surprise and all the emotional moments in his commits. He put
his findings, why he made this decision, and where he found this solution in
the commit msg. I learned a lot just by reading his PR. I think reading a well
organized PR, clean git commits and descriptive commit messages (even the code
review comments are very useful) is one of the best ways to learn in work,
especially for new hires.

------
jodrellblank
20 years after UTF8's creation[1], still having to spend an hour of your life
"fixing" your content for tools which only handle US-ASCII.

[1]
[https://en.wikipedia.org/wiki/UTF-8#History](https://en.wikipedia.org/wiki/UTF-8#History)

------
kenoyer130
While humerous this comment is way to verbose. We prefer the following
template >

Issue: What is the problem we are attempting to fix

Cause: What is the root cause of the issue, since with bug reports this is
usually much different then the random musings of the reporter

Fix: How does the commit address the cause.

Each of these should be 1-3 brief lines

------
ilitirit
This really just depends on your team/company/culture.

Lengthy commit messages are not really required if you have associated tickets
in a bug-tracking or project-management system. More often than not, you'll
just be duplicating info.

~~~
Tactic
This is true until the company changes the bug-tacking and project-management
software without properly porting over everything because they use different
identifiers.

I tend to put a link to the external system with a very brief explanation,
allowing someone to quickly assess the what and why with the ability to dig
elsewhere for more detail.

~~~
ilitirit
You could say the same for improperly porting commit messages when switching
version control systems.

------
mcgwiz
Some of this background decision-making information can be included as
developer documentation, whatever form that takes, e.g. as comments (usually
for low-level) or sibling README file (usually higher-level).

Commit logs will have the greatest detail, but they also are the costliest to
dig up, often requiring multiple rounds of `blame`. They are therefore most
appropriate to include information pertinent at integration-time, namely code
review context/justifications.

Merge commits (such as those created during typical PR/MR merges) have similar
potential to include explanatory background, but at a coarser granularity,
e.g. feature level.

------
hayd
Adding a test to prevent this error in the future would also be nice to see,
something to mention in code review... Which the commit message makes much
easier (without explanation this diff is confusing).

------
Chris2048
Should this go into a commit message, instead of an issue/ticket?

~~~
adamlett
I say yes. I like to keep information about the code as close to the code as
possible. Issue trackers come and go, and even if you keep the same issue
tracker around, how are you going to relate the change in the code to the
particular issue down the road?

FWIW, I also prefer READMEs to Wikis.

~~~
Chris2048
> Issue trackers come and go

What do you mean? Just put an issue ID in the code and/or commit.

~~~
adamlett
Let’s hope the SaaS issue tracker you’re currently using never goes out of
business or changes the product in a way that makes it worse for you. Or, if
you host your own, that it keeps you satisfied in perpetuity.

Referring to the issue ID in the commit message is a fine practice _in
addition_ to writing good, comprehensive commit messages. Commit messages that
consists only of an issue ID are – in my experience – utterly frustrating to
deal with. They tell you nothing more than this change is somehow related to
this or that bug or feature, but not how or why.

~~~
Chris2048
> Let’s hope the SaaS issue tracker

So the solution to a unreliable issue tracking solution is dumping that
responsibility on your VCS? Why not fix the concerns you have with your issue
tracker?

> writing good, comprehensive commit messages. Commit messages that consists
> only of an issue ID

Who said anything about only including a tracker id? The issue here is the
extra verbosity in the commit message. What will the tracker tickets contain
that isn't in your "comprehensive" commit message?

~~~
adamlett
* So the solution to a unreliable issue tracking solution is dumping that responsibility on your VCS? Why not fix the concerns you have with your issue tracker?*

… Or, and hear me out, how about not worrying about that, and just use your
VCS to accomplish something it’s imminently well suited for?

Also, how do you propose I solve the issue of the issue tracking service maybe
going out of business or that of a more compelling product coming along?

To me, the primary purpose of an issue tracker is to collaborate on and track
work in progress, and that’s what I use them for. I don’t find that they are
particularly valuable as historical records of the source code.

------
SlowRobotAhead
WHY > WHAT... really helped my documentation, comments, commit messages. I
think it’s an under utilized part of coding.

I just can’t wait for bigger companies to get onboard. At least in EE/CE it’s
tough trying to figure out INTENT sometimes. I see the code, service, headers,
docs but you’ve never told me how you intent for me to use this! Maybe your
plans were awesome but would change how I was planning to work your thing in.
A single page on INTENT would go a long way sometimes.

------
toastking
I really like Google's guidelines for commit messages because they enforce a
style like this. It really makes dealing with legacy code much easier when you
can look at past commits and see that your predecessors were thinking.
[https://google.github.io/eng-
practices/review/developer/cl-d...](https://google.github.io/eng-
practices/review/developer/cl-descriptions.html)

------
ryantgtg
I feel kinda dumb. I've made many 1,000s of commits since 2011, and I never
realized until now that commit messages can have a "body."

------
hleszek
To avoid those kind of issues, non-ascii characters are forbidden in our code
base. They are automatically verified in a pre-commit git hook.

~~~
Symbiote
I intentionally add non-ASCII characters to our code, so that an incorrectly
configured IDE or bad tool fails.

75% of the development team has at least one non-ASCII character _in their
name_ , so it would be pretty rude otherwise.

It's much better to knowingly reject a tool at the start, since it can't
handle ordinary characters, than find out a year later with the first e.g.
British customer that it can't handle "£".

~~~
kortex
Gmail ignores anything past the + in username+foo@gmail.com. I wonder how much
bobby-tables-esque havoc I can wreak with name+£€ϵ@gmail.com.

Edit: already found one. Leet is supposed to end with Compart › unicode “”
U+2608 Thunderstorm Unicode Character.

Doesn't show up on my comment.

------
Vinnl
I like spending some extra effort on my Git commits (really, typing a message
like this doesn't take _that_ long, compared to the amount of time spent doing
the change in the commit). It's just a shame that both GitLab and GitHub do
not render Markdown in the body of the commit messages, and present them like
actual prose rather than a wall of monospaced text.

------
AdrienLemaire
This is a lovely commit, thanks for sharing it.

Over the years, I took the habit to request from my coworkers to write
semantic commit messages, like
[https://www.conventionalcommits.org/](https://www.conventionalcommits.org/)

You can use git hook libraries like the python pre-commit or javascript husky
to check your git commit messages format.

------
Pxtl
"1 hour of my life I won't get back".

I wish. You know when this kind of bug happens to you it blows away half a day
_at least_.

------
derefr
I’m torn about whether I’d like to see this kind of information in a commit
message, vs. Something more like:

“Remove parser-unsupported character. Closes #340295.”

...where ticket 340295 (wherever, not _necessarily_ Github Issues) goes into
more detail about the cause, investigation, and resolution process, as a
history of the evolution of said process across a conversation.

~~~
pojzon
IMHO you should pick a right medium for some kind of messages and I dont think
git commit message is the right medium in OP example. Most companies have
ticketing tool to keep track of additional information like: how long did it
take to solve that issue, was there any input from other people, long "marked
up" message explaining what was wrong, how it was fixed and tested (markup is
a lot easier to read than console log).

Using ticket number already forces you to use "the right tool" to view the
message.

IMHO I would consider OP example as a bad practice and your example as a
better solution.

~~~
derefr
The other side of this argument—why I’m torn—is that the git commit message
isn’t necessarily written by the developer who developed the solution, but
might instead be written by a project maintainer who received the solution as
a patch, or is copying a fix from a downstream or sibling-fork project, as a
standalone patch.

In other words: if you have a ticket tracker with this information captured in
it, it makes some sense to just link to it. But if you have a _mailing list_
with this information captured in it—in only the loosest amalgamation, where
there’s no clear “thread” that contains the whole discussion, and the original
developer of the patch might not even be _a part of_ that discussion—then it
seems like it’d be important for the final committer to write their own
summary of the events that led to this commit, such that people can understand
what went on if they weren’t following the list. And where do you put that
summary? The commit message.

I would argue that _maybe_ this is a core part of git’s design, given that it
was developed specifically for the LKML style of “patches first, sent to a
list, and then discussed in the context of what they solve”, rather than the
GitHub style of “discussion first [on open issues] sparks PRs that attempt to
solve [i.e. close] the issue.” Git assumes that you, as an “editor”, are going
to be summarizing an otherwise- _illegible_ discussion history for the benefit
of the people viewing the commit; and so it provides a multi-line commit
message as a place to stow that _editorial_ summary.

------
hnruss
I ran into a similar issue a few years back. There was the same non-space
whitespace character spread throughout the codebase. I tracked it down to a
single developer, who had no idea why that was happening. My guess was that
they were copy/pasting a lot from MS Word documents, but we never found out
for sure.

------
nickysielicki
The worst thing about Gitlab and Github is that commit messages are not
immediately editable in a PR/MR conversation. You can find conversations like
this all over {gitlab,github}-dot-com but you cannot find them in commit
messages anymore.

    
    
        Closes #123456
    

instead of actual background.

It's bad for your codebase.

------
reacweb
Hidden characters again. The answer on stack overflow I am the most proud:
[https://stackoverflow.com/questions/41061400/perl-join-
strin...](https://stackoverflow.com/questions/41061400/perl-join-strings-
incorrectly/41062206#41062206)

------
rbanffy
My personal favorite is one where I actually fixed a bug by flipping one
single bit.

[https://bazaar.launchpad.net/~rbanffy/maas/bug-1443627-incre...](https://bazaar.launchpad.net/~rbanffy/maas/bug-1443627-increase-
node-release-time/revision/3820)

------
carapace
Gah... About a third of my commit messages are just "minor cleanup" or a
variation. Should I be ashamed?

~~~
sixstringtheory
I think shame is an awful motivator. Instead I would praise you for
identifying an opportunity to improve :)

------
codegladiator
Should have been in a doc or wiki instead of commit message.

I have never seen any dev searching for error messages in commit messages.

For the rest of the points (makes smarter, builds trust and compassion), if
it's so worthy put it on the blog (like this blog post itself) so it can has a
potential to reach some reach some audiance.

~~~
lucideer
> _I have never seen any dev searching for error messages in commit messages._

I've seen many devs search for error messages in Github search. That often
turns up results in people's comments in issue threads, but the search also
includes commit messages.

~~~
codegladiator
I have had github issues come up for search results frequently, but never a
commit message.

But then again, I am not saying "don't write the story". If you think you
found something worthy, just write a blog post or even a pastebin/gist would
be better in terms of the number of people it reaches.

------
ajdlinux
This is one thing the Linux kernel does comparatively well compared to most
open source projects.

------
ronjouch
Related: Greg Ward - Documenting history, or How to write great commit
messages: say what, not why.
[https://www.youtube.com/watch?v=Jb6ij4eRu6c#t=378](https://www.youtube.com/watch?v=Jb6ij4eRu6c#t=378)

------
sethammons
One of my favorites, and I can't find it now. Someone's last commit message on
the deprecated perl project was in 3D ascii art; something along the lines of
"No More Perl." I have a few projects I'd like to write that to :)

------
hyperpallium
General education in a commit is questionable... OTOH _find -exec_ and
escaping the ';' (or '+' for xargs-like one line) was helpful (hard to parse
--help, though manpage is clear). Now I don't know what to think.

------
tempodox
The Holy Order of Git Commit Log Bikeshedding and Overengineering have their
field day. And they all have it wrong. Any commit log that doesn't compile to
an automated build script isn't worth the bytes it's made of.

------
yuriko
A similar story: [https://hal.archives-
ouvertes.fr/hal-01340384](https://hal.archives-ouvertes.fr/hal-01340384)

------
luord
What I gather from this is that commit messages are a better place for
documenting stuff like this than polluting every line of code with often
redundant comments.

I like it.

~~~
sethammons
I think the git log is an interesting place to document this kind of thing.
Also, there should never be redundant comments. I do think though that lots of
folks put things in the git log that _should_ be a code comment. For myself
(as most of the people I can think of that I work with), we don't reference
git commits unless we are actively investigating a previous change. You should
not hide reasons for code being the way it is in the git commit; it should be
exposed for direct observation to someone who might edit the code. Ex: '// the
following delete call is required to remove the item from the DNS cache to
ensure the test validates non cached dns items'. That should be in the code.

------
takeda
A very descriptive commit that doesn't actually fix the bug, only removes the
offending character that was triggering it.

------
vpzom
But why was this a problem in the first place? Pretending non-ASCII characters
don't exist isn't the right solution.

------
irrational
Why are they using us-ascii instead of UTF-8?

------
kgwxd
I had a similar issue with zero-width space recently. Why in the world does
that character even exist?

~~~
lolc
I've used it to hint good line-break positions in a text body where the soft-
hyphen does not apply.

------
Ensorceled
I often review commit logs of my teams, especially while we are tracking down
problems or I'm making sure the release notes capture everything.

There has to be a balance between this and "WIP"; I'm imagining trying to page
through the commit log to see what changed when every 1 line change has a 35
line commit associated with it.

~~~
1f60c
That’s the beauty of it, the first 50 characters of the first line (IIRC) will
be shown as a summary, and this one summarizes 35 lines in seven words.

------
iicc
This would be terrible without a good subject (the first line).

------
keithgabryelski
seems like the commit messages lines are in reverse order.

tell me what you did.

then tell me why you did.

leave the saga for the end text so I don't have to read through your musings
to get to the meat.

------
_pmf_
I'm just told to not write so much bullshit.

------
l8again
I love descriptive git commit messages. For those complaining about the
length: 1) Just read the title 2) Maybe have TL;DR section for a summary, and
details for who cares. 3) Use pretty printing for git log

Having a rich commit message is extremely important for capturing code review
discussions and design decisions and glue things together for the set of
changes in a single place. The advantages far outweigh any negatives from a
short commit message that will not give you the "why" of the solution.

------
nkingsy
Just link to the bug

------
doodpants
TL;DR: Written language can be used to communicate information.

------
ilovepeppapig
RIP git log

------
lcnmrn
Someone typed and commited that whitespace character on purpose.

------
d--b
Yeah but because git is a command line tool, it doesn’t really encourage you
to do this in the first place...

The title of the commit was enough for me. I wouldn’t have read the content
anyways

------
airnomad
When tax payers foot the bill it's easy to spend entire morning on a single
line commit.

For many or most guys out there, reality is way different. For one, it's an
actual reality, not VC or government funded Utopia.

