Hacker News Reader

Comment by networked | Hacker News Reader

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

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

View on HN

I think GitHub has broken us a lot here.

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

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

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

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

it doesn't seem that GitHub is willing to change their code review tools

They only have $350 million in funding. What do you expect, new features?

(SpaceX launched rockets into space with $100 million of private Elon Musk money. $350 million from VCs helps GitHub make... webpages.)

A late update on this subthread (I wrote the GP): I found your comment very insightful when I first read it. That the VCS applies a series of patches that are essentially standalone to the initial blank state is something that gets obscured when you use GitHub and similar tools. (And GitHub is a big influence — for me it's a major reason for using Git a lot more than, say, Mercurial or Fossil.) I have since given the matter more thought and have adopted the imperative mood subject line style for a new project I started.

As for "addressing the system", I have decided for now to not do it at all in my subject lines to avoid the confusion.

I find it personally amusing to notice I tend to take the same approach with my commit messages, while never quite intentionally setting out to do so. Reading your comment has left me mildly introspective, wondering why I do so. I have some thoughts that aren't particularly relevant here, but thought it worth mentioning this is a particularly helpful approach--if only because I default to reading imperative msgs as actions/expectations of the system worked on, and indicative msgs as actions of the committers.

I think you should usually be able to reword any "self-action" commits into system action commits.

For example, you could say "Don't issue unnecessary cache directory warning".

Prefacing a commit message with add/remove/delete seems unnecessary.

So how would you suggest to reword "Refactored invoice parser" for instance? I'm not asking the system to do anything here: in fact, it would be quite unfortunate if it would start doing anything different from what it does already. No, I'm just stating that this part of the system was a mess since its original creation back in Jurassic period and I just cleaned it up.

I would reword "Refactored invoice parser" entirely as that message is about as useful as "changed code".

"parse invoices better" ;)

"Refactor invoice parser"

Have you read the comment I'm answering to? I'll repeat the key sentence for you:

> you should usually be able to reword any "self-action" commits into system action commits

So your suggestion here is completely irrelevant, as "system" doesn't refactor anything.

That's not how I've normally seen the advice to write imperative commit messages get interpreted. Quoting Documentation/CodingStyle from the Linux kernel (whose commit messages follow that pattern):

Describe your changes in imperative mood, e.g. "make xyzzy do frotz" instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy to do frotz", as if you are giving orders to the codebase to change its behaviour.

Or, if you prefer not to anthropomorphize the codebase (because it hates that), you could also think of it as instructing someone to make the change (and then supplying a patch implementing that instruction).

And a quick search through the Linux kernel git log turns up 1416 messages of the form "subsystem: Refactor ...".

I guess the important thing is to be consistent with whatever mood you choose.

Reply on news.ycombinator.com