Atom – Git commit messages | Hacker News Reader

Atom – Git commit messages

atom.io

86 pointsselvan54 comments

Cool fun idea - I dont understand though whats the reasoning behind using the present tense.

$ git commit -m "Add email integration on /email route" sounds weird for an activity that has been completed.

Because generally you're reading commits that happened before and you want to know what happens when you apply the commit.

It goes something like this.

"Hmm, I wonder what would happen if I merge 1231knf?"

It would "Add email integration on /email route"

Otherwise it would be something like

"What happens when I merge this commit?"

"Added email integration on /email route"

It's considered as best practice when using Git to write in present tense.

That's one interpretation. Another is you're looking at git log and it's all historical. The best practice bit seems to boil down to "because Linus said so." The rest of the git commit best practices seem to fall into a similar boat.

I'm of the mindset a team can be mature enough to pick what works best for them. If the idea of a commit message is to convey useful info, imposing hard rules like 72 chars or tense seems a bit draconian. The worst change GitHub has made IMHO is truncating messages (particularly because the truncated message often ends up longer).

The reason for the 72 character limit is so that shortlog messages on an 80 character terminal which are indented by one tab aren't truncated, as I understand it.

I get that. And in certain scenarios where even pagers aren't available require that. But I'd expect that team to handle it, not for it to be a general purpose rule. In contrast, a Nokia postage stamp feature phone can display a message more than twice as long (SMS - 160 chars). Limiting to 72 chars across the board seems to be more dogmatic than anything else from my POV.

I think that the boat already sailed, there are many tools that assume that shortlogs are 72, and can be displayed on a single line, and format accordingly, including GitHub for instance. Besides, whether it's 72 or 100, it makes sense to force people to have a concise summary.

GitHub's approach is one reason I've started using BitBucket more. GitHub didn't always used to do this. I've assumed they started so they could have fixed height commit displays in their commit list. It seems weird to force this on people otherwise.

Angular has similar rules.

Maybe it's because "Add" is shorter than "Adding" or "Added"? When I first worked on a project that followed the Angular pattern, the guy ramping me up said "Just imagine that you're commanding the computer to do something, and use that tense."

I believe the motivation is explained here - http://tbaggery.com/2008/04/19/a-note-about-git-commit-messa...

Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug." This convention matches up with commit messages generated by commands like git merge and git revert.

That mostly just passes the buck to why do merge and revert use the imperative? Simply being consistent with them doesn't seem like a very strong argument.

It's a standard to use the imperative mood in writing commit messages - the Linux kernel enforces this[0], as do a lot of other projects.

It makes more sense if you consider a commit to be an independent "thing" in a list, and you follow the list from start to finish to end up with the current repository state, each commit being a command.

[0] http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.g...

I thought it was very meta amusing that the author was trying to tell users how to write commit messages when the number one rule of commit messages in my book is explaining WHY the commit exists. Why does this patch change this or do that. So it was amusing when he lists commit rules without explaining why they are rules. But I was saddened when I got to the end and missing from the list is 'explain why'.

Why did you 'Add feature...'? Why did you 'Move cursor to...'?

I did stuff // Increment i by 1

Why I did stuff // Increment i by 1 to not have a off by 1 bug

I see three different types of commits in my codebase, usually.

* The big fix: This is the commit which usually is too complex to be explained in a 72-characters message. Usually it refers to an issue number on the project's issue tracker, which in my case is Github.

* The medium fix: This is a commit whose "why" fits properly into 72 characters, i.e. "Add classes to validate user input only on Friday".

* The small/obvious fix: This is a very small commit, usually fixes obvious issues like CI builds, misspellings in doc files, missing semi-colons, etc etc.

In the last case, I find it appropriate to write the "how" rather than the "why" in the commit message, since the why is already obvious. i.e. "Add missing comma on object identifier".

>the number one rule of commit messages in my book is explaining WHY the commit exists

The commit message should say what changed, not why. Comments are for explaining why the code does what it does.

Good commit log: http://git.savannah.gnu.org/cgit/guix.git/commit/?id=fb519bd...

Comments tell why the code does what it does. Commit messages tell why the code does something different than before.

Example comment: i++; // because server starts counting at 0 (not 1)

Example commit: Our customer switched to bar (from foo), which starts counting at 0 instead

The diff shows you what changed. The commit message is a comment on the diff and absolutely should say what it's for.

This enables you to easily compile release notes, for example.

Yes, it should say what it's for, but it shouldn't need to explain itself any further. Sorry if I didn't make that clear. For example, if someone refactored something, the commit log can simply say "Factorize foo", it need not explain why they were refactoring in the first place.

That works as long as you're adding code. But what about when you're deleting code? I absolutely want to know why you've removed something.

The "why" can live in the bug tracker, as a feature or fix may have several commits attributed to it.

For larger centralized projects, I have found a requirement on issue numbers in commit messages to work well. It makes a whole lot of management issues easier.

If issue numbers are the only requirement, is it okay if every commit only includes an issue number and no text at all? If not, why not? If they say something should it be the exact same thing as the issue title?

IMHO, no. You should be able to read a commit log and understand what has been done. But if the issue titles are good enough they could absolutely be used as commit messages. Many issues leads to multiple commits however, so what you want for message is a description of the individual commit.

Say you want to apply a certain commit to your branch, it makes more sense to "add" a feature than to "added" a feature.

What does a commit do? It adds/fixes/breaks, it doesn't added/fixed/broke.

Thats one way of looking at it. Another way is - What did I(the developer) do in the commit? I added/fixed/broke, right?

"/email route: Email integration added" is my favorite way. Same thing with code naming, I always put the widest context first, then narrow down. With this habit I spend a lot less time thinking about names.

I tend to use that style because it matches git's generated commits ("Merge ...") and it saves a few characters. I found that when using a different tense ("Adding" or "Added") I would run out of characters more often.

The past sounds good, until recently I was writing my commit messages using it, but when you start making pull requests on GitHub, you realize that it makes a lot more sense in general to use present for the titles of your commits.

A commit can be seen as a patch, which has a single purpose: "Add...".

I'm sure this isn't real or just a fun joke. Please don't consider using a :checkered_flag: emoji to indicate you are fixing something on Windows, or any of these other icons.

Or:

Please consider using these emoji, but please don't anticipate or expect other developers will have any idea what their usage means.

Well, this is specifically for contributing to Atom - and if you look at their commit messages it looks like they're at least somewhat doing just that.

They are using it though:

https://github.com/atom/atom/commit/f151697c4cd0c22cfac9ab19...

https://github.com/atom/atom/commit/325d95ed35bb3f1a1741e77d...

https://github.com/atom/atom/commit/a606fc516b19ee8753016835...

> Please consider using these emoji

Fine with that, but please also write longer descriptive commit messages. For example:

  > git log -1 3b5bb1501ce7af8f857af7621fc0d5f86fb4fa93

  commit 3b5bb1501ce7af8f857af7621fc0d5f86fb4fa93
  Author: Ben Ogle <ogle.ben@gmail.com>
  Date:   Tue Jan 6 17:09:59 2015 -0800

     :lipstick:

Tells me nothing. Nothing! At a glance the commit messages for the atom repo are poor:

  atom > git-mean-commit-message-bytes | grep '>'
  >ALL 147

You would hope github and git users would grok the power of git's commit messages, but hey ho...

Well, if you read their guide it says that :lipstick: means:

"improving the format/structure of the code"

So I guess this code just changes spaces or something like that, I don't know I'm just reading what they do, they might do something else, I'm just following the instructions that everyone contributing to the code should.

OK, the guidelines explain the meaning but the message is still not descriptive enough. What happens when one of those commits breaks something? If i ran a bisect and the offending commit had the message:

  :lipstick:

I would be tempted to revert the commit because the message tells me nothing about why the change was made. A commit message should be future proofed, even if the code it relates to can never be.

I'm guessing that's intentional. The idea is that if you are going to reformat code, it should be the only thing you do in a change; in other words, don't commit a change that both changes the semantics of the code and changes the formatting.

The principle is that formatting is orthogonal to other work and therefore shouldn't be mixed in. Unless you do something wrong, formatting changes are harmless so they can be scanned past by someone reviewing a changelog.

Here's a good discussion of the practice on StackOverflow: http://stackoverflow.com/questions/2214480/committing-when-c...

> Unless you do something wrong

Therein lies the rub; when something goes wrong i want a commit message that explains why that formatting change was made.

  :lipstick: - add missing # char, as per conventions

Would have taken all of 5 extra seconds to write and is a lot better future proofed. Remember, a commit message should explain why something changed and not just what changed.

Are those emoji an attempt at vendor lock-in? Want to contribute to our project? Use our version of git. I hope this doesn't spread elsewhere.

I'd accept showing icons when certain commit/commit message criteria are met, for example "refactoring" in commit message or perhaps whitespace commit would trigger the lipstick icon. But putting :lipstick: as the first word in your commit message? What user davexunit said.

Aren't these standard? There's the beer icon showing up when using Homebrew on OSX, I guess the other ones would show up too on a `git log`.

The Unicode characters are standard.

However, encoding them as ASCII strings such as ":lipstick:" is not, and that ASCII string is what goes into the commit message. git will not decode these messages as the emoji characters, as far as I know, and I expect that Linus Torvalds would have some choice words if that were a feature request.

Sequences such as ":lipstick:" are a hack to work around the fact that PCs (as opposed to phones and tablets) are bad at both inputting and displaying emoji.

I came across the "tags" that the AngularJS uses, and have found these to be a lot more relevant to my projects. I agree with @mrcwinn that expecting other developers to understand the usage of some of these is asking too much (`:lipstick:` ??? ).

https://github.com/angular/angular.js/blob/master/validate-c...

The format they enforce is here - https://github.com/angular/angular.js/blob/master/validate-c...

If done right then these tags can be invaluable when using tools like `git-bisect` - you can safely ignore the ones marked `docs` or `style` (assuming you are not working with a language like Python).

Not to mention you can build automation around like, for e.g. automatically generating release notes.

The lipstick one seems pretty silly - especially if one is familiar with the idiom "lipstick on a pig".

They contradict themselves. Should it be present ("Is/are less buggy") or imperative ("Be less buggy")?

Imperative present. These are compatible. Writing a commit also implies the use of verbs related to actions.

The best git commit message style guide in my opinion is Erlang OTP's "Writing good commit messages"[0] wiki page.

[0] https://github.com/erlang/otp/wiki/Writing-good-commit-messa...

I have been using atom sense its initial beta release and it has come quite a long way. Some of these contribution guidelines might seem silly (such as the emoji) but it definitely works for the community.

Did they improved startup time of the editor? Last time I tested it (Windows 7 x64bit) it took good 3-5 seconds for it to start.

Do Android-centered commits use the Linux emoji, or should we be lobbying for a mobile-device emoji?

>Use the present tense ("Add feature" not "Added feature")

Agreed.

>Use the imperative mood ("Move cursor to..." not "Moves cursor to...")

Agreed.

>Limit the first line to 72 characters or less

Agreed.

>Reference issues and pull requests liberally

Agreed.

>Consider starting the commit message with an applicable emoji

Fuck off. This is completely useless and doesn't deserve 14 examples when the above sensible directions are so brief.

It's their project, if you want to contribute why not follow their guidelines?

The emojii are just shorthands for [CodeImprovement], [Feature], or whatever you might otherwise tag commits as.

"Fuck off" - seriously? Why use such inflammatory language in your post. A simple "Disagree" would have sufficed.

IMHO the tags are a quick way to filter commits by each of those. The images are just for quicker reference.

How is "lipstick" and "checkered flag" a more appropriate tag than a more specific, less ambiguous and more concise technical word?

Most projects already use tags like "FIX" "CHANGE" "NEW" etc etc, there really is no reason to use ambiguous emojis.

These are small and coloured, so they're easy to see in a list.

They are definitely not small and coloured on my terminal screen. Maybe we should update git or github with proper tracking and tagging (wait, git already supports tags! But that's for a different thing anyway) instead of using something that was not intended for this purpose. Especially because, as I said, it's ambiguous and it really doesn't bring any benefit on the table.

>"Fuck off" - seriously?

It's an exaggeration for effect (the downvote effect, I suppose), but recommending emoji as a commit log guideline is totally silly. I cannot take this document seriously.

So... emoji, but still horrible performance? Moving on...

Really? Downvotes without a response? Seems awfully cowardly. So I'll just assume the performance has improved to the point that opening a large file doesn't cause it to lockup for an hour? Because that seems a lot more important to me than emoji's for commits...

*nope, just tried it again, performance still blows.

The downvotes were (I assume) because you are going completely off-topic. This isn't about performance of the Atom application, it's about their commit guidelines for contributing to the project.

Editing your comments to attack people that downvoted you is only going to make the situation worse. Just face the fact that it probably wasn't a good comment and move on.

Reply on news.ycombinator.com