DeepDocs

This morning, when I was casually browsing I came across this gem of a commit from 12 years back.

Now I like git messages as it is a simple yet powerful way to document your code changes.

But this particular message read like someone’s diary, and it made me smile.

This commit was published by a a developer name Dan Carley in 2013, and was popularised by this post titled “My favourite Git commit” 6 years back.

So here is the commit message:

The header of this commit is a pretty straight forward “Convert template to US-ASCII to fix error”, however the body of the message, which I have never seen anybody use, read like someone’s chain of thought.

In a nutshell, the message documents fixing a non-ASCII character bug when executed in an US-ASCII environment.

At first Dan shares he discovered the bug:

I introduced some tests in a feature branch to match the contents of `/etc/nginx/router_routes.conf`. They worked fine when run with `bundle exec rake spec` or `bundle exec rspec modules/router/spec`. But when run as `bundle exec rake` each should block failed with: ArgumentError: invalid byte sequence in US-ASCII

Then how he reproduced it:

I eventually found that removing the `.with_content(//)` matchers made the errors go away. That there weren’t any weird characters in the spec file. And that it could be reproduced by requiring Puppet in the same interpreter with: rake -E ‘require “puppet”‘ spec

And eventually, how he found the offending file:

That particular template appears to be the only file in our codebase with an identified encoding of `utf-8`. All others are `us-ascii`:

From there, he documented his exploration step by step, running commands, checking MIME types of each, and finally isolating the culprit: a whitespace character in the file.

And finally, fixing it by hand.

After replacing it (by hand) the file identifies as `us-ascii` again:

The author ends the message with a sigh of relief, although with a tinge of regret

Now the tests work! One hour of my life I won’t get back..

The level of detail here is what makes this commit message so delightful. It isn’t your typical, almost cryptic fix bug message, but something that feels like reading someone’s diary.

Now commit messages don’t have to read like stories. If you Google best practices for writing commit messages, you will be inundated with resources, with none of them recommending you to write verbose commit messages

The author of “My favourite Git Commit” post argued that the commit message makes it searchable.

Yes, you could search for this bug using git commit search git log --grep "invalid byte sequence" but that’s just not a typical thing in a developer’s workflow. Also, a developer would have to know apriori that this bug is documented as git message.

Should the author have written a documentation instead? In my opinion that would have been a reasonable choice because they are simply more accessible.

My personal take is that the commit itself serves no functional purpose, nor does it help anyone.

Recently, in another post titled “No longer My Favorite Git Commit“, the author Michael Lynch criticised the original post highlighting the presentation of information in the commit as problematic, that it buries the most important information at the end which nobody cares about.

In that post the author investigated the commit thoroughly, and at the end rephrases the original commit message, with a lot more details on the origin of the bug, and with the whole message clearly organised into different sub-sections.

When I read rephrased commit message, it made sense but I could not help but wonder if it would have evoked the same sense of compassion and trust the original commit did. It felt almost mechanical.

Especially in a world that has been ruined by AI slop.

We are just humans, and adding a bit of beauty to the most unexpected places is just our thing.

Let this beautiful commit from 2013 rest in peace.

About DeepDocs

DeepDocs is a GitHub app that helps teams automate the mundane task of keeping docs, like READMEs, API references, SDK guides, tutorials etc. up-to-date with your changing codebase. It is completely free to try.