Hacker News Reader

Comment by why-el | Hacker News Reader

It always puzzled me why his commits (and in fact standard commits) ought to start with a verb that is not in its past form. When I started using git four months ago (such a newbie), I would write something like "Fixed this" instead of "Fix this". Anybody with more insights on this? I am just curious.

View on HN

If you think of the change set as the subject, so the question is 'what does this do?' and the answer is 'fix X' then it makes more sense. Past tense suggests you might be thinking of it as a journal or something that you're not supposed to do with git due to rebase etc.; each commit ought to stand on its own.

That said I don't think this is significant enough to add up to a compelling reason either way.

Your point about rebase is compelling enough for me. :) I thoroughly missed that. Thanks.

Sorry, pardon the ignorance, but how does past tense imply something that would be affected by rebase? It may not be linear history, but it definitely happened in the past. I guess I always looked at more as: "here's a patch", "what did you do?" If it's just a tomato/tomato thing (yeah, that doesn't come out well in text), just let me know.

Because rebase, and rebase -i especially, gives you the ability to break your patches into discrete this-one-one-goddamn-thing patches (which is awkward in a "oh, you committed it? Then you committed it forever" SCM like Perforce or SVN), you should do so. It makes it a lot easier to review than the "so this does X, but also fixes some syntax errors and adds logging" style. And that means you should make the patch comment reflect what it is doing. Some errors here are inevitable but it's something to which I aspire.

Edit: to be a little clearer; your traditional SCM has a write-once-never-change model for the trunk of development. This has a problem in a peer review situation, and the problem is this: I may go forth with the best of intentions to decompose things into discrete patches. But when you get down to brass tacks, changes to the system tend to happen in any given order--you might discover a latent bug when testing your feature that has nothing to do with your feature. Now you have two choices: you can wait and commit nothing until everything is great, which means you're not integrating with the mainline, which means that integrating will be incredibly painful, which leads to locks; or you commit as it comes in the moment, which is much better for integration and much easier to back out partial changes and generally get all of the non-backup elements of an SCM, but which is the very devil to peer review. With rebase -i, it is quite easy to commit in the second style in the moment and then clean them up for peer review later; that is the ability to revise history means you can make decisions immediately without worrying that they will be cast in stone forever and ever anon.

I wasn't always this much of a hardliner on the subject, but my current job uses Perforce as the main SCM and I have realized that I disagree with almost every decision Perforce makes across the board. I still use it, because any SCM is way better than no SCM and I don't want to explain git to everyone else, but my actual development occurs with git-p4.

Thanks for responding. I don't think I necessarily agree, but then again I rarely rebase because I distinctly dislike rewriting history, but I think I understand the rationale a bit better.

so the question is 'what does this do?' and the answer is 'fix X' then it makes more sense.

Better to say "fixes" then, so it's distinguishable from the use in a phrase as an imperative. "We need to fix this."

I've always found it useful to start writing my commit messages as if they begain with "When applied, this commit will..." ex: "Resolve #459." "Fix the PDF rendering issue on older clients." "Revert commit 1234567."

Remone will, and you get more versatile comments.

This is the first time I've seen his commits, but I do the same thing at work, deliberately. I don't pretend to know his reasons, but I've always had fun with the idea that if there were a super high-level language, it would look similar to a commit message and the corresponding changes would take place. And so I have changes that look like "Optimize the foo() function", etc.

I like the "super high-level language" perspective. I imagine commit history like a (journaling file system's) journal, whose commands can be undone and replayed.

A commit can be seen as a changeset. A changeset can be formatted as a patch.

Projects like Git and Linux take their contributions in as patches that are sent to the projects mailing list. As it is not merged in to the master tree at the time of publishing, it would not make sense to use past tense for describing what it should do, if merged.

Thanks to Git's great history-graph altering functions like rebase and cherry-picking, it would make even less sense. You can always take some commit and apply it to new branches or even repositories.

Whether your commit is historical or not depends on your point of view. Git is distributed. For whose repository is it historical? What if I pull out the commit using git format-patch? Is it still historical now?

See his other rant about Github's handling of single-line commit summaries. When space is at a premium it's a waste to past-tensify all the verbs since it inevitably wastes precious characters in the one-line description.

It drives me nuts that I never know exactly when Github will break my one-line descriptions when there appears to be plenty of room left to display the characters. Like this one from Linus:

https://github.com/torvalds/subsurface/commit/bea6637c03a90f...

In my opinion its because your commit log should read like a novel and not like a history book.

It's also simpler and promotes less convoluted phrasing.

I haven't read many novels lately, but I always thought they were written in past tense.

According to http://tbaggery.com/2008/04/19/a-note-about-git-commit-messa... (linked in one of the comments in the github discussion) it is for consistency with the commit message generated by 'git merge' and the like.

I can think of a few reasons for the grammar rules in the commit message...

It is direct, concise, consistent and tends to active voice rather than passive voice. Further, not everyone writing or reading the messages will be a native English speaker. Avoiding past-tense forms just makes it easier.

I am actually not a native English speaker and I always thought that this was hard to understand specifically because English is my first language. But again folks provided enough information for me to understand the reasons for it to be this way.

It is part of the git best practices:

http://git.kernel.org/?p=git/git.git;a=blob;f=Documentation/...

The HEAD version is a bit different (less clear?), although the intent is more or less the same:

"describe 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."

http://git.kernel.org/?p=git/git.git;a=blob;f=Documentation/...

Exactly, same as when you are cherry-picking.

Reply on news.ycombinator.com