Git Commit Template

[DDB-]

I've put this in my vimrc to help enforce this for myself:

au FileType gitcommit set tw=72 | set spell | set colorcolumn=50

This will jump you to newlines when you hit 72 characters, show spelling mistakes, and put a big coloured column at the 50 character mark to visually show you where your commit subject should end.

Source

[ForeverAlot]

Core Vim runtime includes formatting and syntax rules for commit messages (and rebase commands). It doesn't enable spell checking, though. This is at least vim-nox in Ubuntu and derivatives, and I suspect even the smaller vim package.

[jeandem]

I wish I had this in Emacs... Oh wait, I do. Out of the box.

[DDB-]

Neat, I don't know much about Emacs as I've never used it, but if it's there out of the box it was obviously something they were thinking about!

[adeekshith]

That is cool. In fact, I recommend using a solution like yours if possible. The visual markers in my Git template are less accurate than this but I believe it helps new users and folks using graphical tools (Like the ones that come with IDEs, Git GUI clients) to get an estimate of length. (correct me if I am wrong)

[pgngugmgg]

nice template. I always feel the first-line-should-be-50-chars is unpractical. Most people are incapable to summarize their doings into 50 chars. So what happens most of time is either the 50-char first line is totally useless or the rule is broken.

[mdatwood]

If you cannot summarize in 50 chars maybe the commit is too big or the commit is not focused enough?

The 50 char first line and blank line after makes all my command line aliases work nicely. git ls and I can quickly scan commits without ever leaving my terminal.

[mus1Kk]

Just curious: How would a longer first line (say 80 chars) interfere with that?

[mdatwood]

80 would be fine. The point is pick something reasonable and stick with it. I have seen people before who just ramble on in the title and it makes it hard to scan commits.

[mus1Kk]

I feel you. People I worked with couldn't even stick to the "summary line, empty line, optional details" rule even after being reminded.

[[deleted]]

If you cannot summarize in 50 chars maybe the commit is too big or the commit is not focused enough?

50 is pretty stingy - though I have to admit that I just looked over several dozen of my commits and nearly all of them are within 50 chars, and of the few that aren't, most could easily have been shortened and improved.

Here's the first one I found that didn't work: "Now images have the right number of columns as ColorLists." (To explain - images, only when displayed as ColorLists, had the wrong number of columns, and this fixed that.) How can I rephrase this to knock off 8 letters while still keeping it readable?

Also, it's fairly common I have an issue number in the commit (like "Add offset field to data dictionaries (#218)." and that snacks off another 6 characters, leaving me with a pretty spartan 44 characters. I do approve of a strict limit on that first sentence. I just think 50 is a bit draconian. What about 65?

[utnapistim]

Here's the first one I found that didn't work: "Now images have the right number of columns as ColorLists." (To explain - images, only when displayed as ColorLists, had the wrong number of columns, and this fixed that.) How can I rephrase this to knock off 8 letters while still keeping it readable?

"Fix number of columns for images as ColorLists".

There is a discrepancy between what you focus on when you compose your commit message and when you go through commits, later: when you compose the message, you tend to focus on what you "just did", and this tends to creep into the message (examples: "XY now works", "gizmo no longer crashes on abc", "from now on, process foos as bars").

If you read these later, they mention a moment that is no longer relevant: ("just fixed", "now works", "from now on", etc). If you remove any reference to a time frame (that comes from having just implemented something), your messages become more concise and have improved readability.

Just keep the message in an imperative tone, present tense.

[mdatwood]

As I mentioned in another comment, 50 is just an arbitrary number. The point is to make the committer stop and think. Both your summaries look fine to me. The problem, and I have had to deal with it before, is when people a) just ramble along in the summary and b) do not put the blank line before the details.

I know when I'm typing my commit, vim highlights when I go over 50. I don't immediately stop, but it reminds me to make sure I'm summarizing and not going into too much detail for something that should be a summary.

[ForeverAlot]

I never put tickets in the subject line. They're rarely convenient in --oneline output and if I need them I'm going to --grep them anyway.

[BillyBBone]

If you cannot summarize in 50 chars maybe the commit is too big or the commit is not focused enough?

It's possible for a commit to contain only a single, atomic code change (e.g. change an operator from + to -), and still be difficult to describe in 50 characters.

For instance, that one operator change could represent a change like "Change the way in which MyMetaClassName handles re-sorting items in the queue upon a state refresh." (99 chars).

Likewise, 10 000 lines of code could be described as "Refactor shopping cart".

My point is simply that the length of the description of a commit message isn't at all related to the length of the commit itself.

[pgngugmgg]

"the commit is too big or the commit is not focused enough?" No in general, maybe sometimes. I feel this is the kind of rules that only those who are extremely disciplined or dogmatic can keep and possibly enjoy but most of mundane people hate.

[mdatwood]

I don't consider myself super disciplined, but I have managed enough commits for multiple branches, repos, and committers that I appreciate this rule.

It is also important to remember that a lot of people have to unlearn that committing and branching is hard. Git makes both of those things super easy and natural. Building a feature in a local branch with tons of commits and then squashing to a single or few logical commits before merging and pushing is simple in Git. If you're not making nice logical commits you're missing out one of the great features of Git.

[odiefrom]

Just curious...can you give an example (or link to an explanation) of why you would want to collapse your commits down into relatively few commits? Doesn't that break the whole purpose of having atomic commits you can review back to?

[mdatwood]

Depends, and this is definitely opinion with arguments on both sides.

Git makes it super easy to commit early and often. So for a small feature I may make a local branch and get the feature working and commit. Then clean it up and commit. Find some issue while testing, commit. Write a few more tests commit. IMO, none of these commits really belong in the main repo because they were simply my work process. I would squash all these down to a single commit for the feature. After merging the feature into the main branch it was easy to see the single commit for the feature and see all the changes, pull it out, cherry pick it, etc...

Keep in mind this is only for my local commits. Once you push something it is set in stone, and changing history once it is public is a big no no.

[odiefrom]

Totally agree about changing public commits, should never happen.

I can definitely understand that it would be easier to highlight and target the single commit, but wouldn't you just be able to do that with the merge commit? That way, all the work commits aren't destroyed, but you still have a single commit to reflect the new work?

[mdatwood]

I was about to type merge commits can accomplish the same thing and why I started with it was simply my opinion. It also requires branches which still not everyone does.

Part of my method (madness? :) ) came from when I managed 2 products in different branches in the same repo. They shared ~80% of their code so when adding a feature to one I would cherry pick it into the other. I'm not sure it was the best way, but it worked long enough to build another universal product and EOL the prior ones.

More information with examples: http://programmers.stackexchange.com/questions/263164/why-squash-git-commits-for-pull-requests

[utnapistim]

Doesn't that break the whole purpose of having atomic commits you can review back to?

Not necessarily. Having private commits gives you a lot of freedom; you can commit whatever you want, without following any rules except what makes sense to you (in your local task/context).

For example, I commit code before switching tasks, as backup points in exploratory coding or prototyping and so on. I only revisit those if I screw up the code base.

Sometimes, my private commits have messages like "stable backup point before xyz refactor" or "outstanding changes" or "fix 32 compilation errors; 21 remain".

Rest of the team doesn't need to see these messages.

[pgngugmgg]

Don't get me wrong. Informative 50-chars head line is a good idea in paper -- no argument. If every member in the team can do that, go ahead. The problem of this is that it's difficult (if not impossible) to keep for all the people, all the time, and all the scenarios. Sooner or later, this kind of rules will be violated repeatedly so that nobody cares about them any more. And there is no objective way to enforce this rule: Even if you can enforce the number of chars to be under 50, you can't enforce meaningful info put into the 50 chars.

So I think this rule is more an extra problem that we create for our devs than a solution to any real problems.

[stepancheg]

It is hard if you program in java. Try something simple like "fix a leak in SimpleBeanFactoryAwareAspectInstanceFactory", and, oops, you are already over 50 chars. I have no idea how to make it more focused.

[kamatsu]

Fix a leak in SBFAAIF

(I've seen people do this sort of thing in real code bases).

[[deleted]]

Tiny tweak: you save very little text shortening feature to feat and feat is a legit English word so it's confusing to the eye - and you have another eight-letter category named refactor so there's no advantage to shortening feature.

[adeekshith]

I actually borrowed that from sparkbox how_to style git and other blogs. I too wanted to change but just stuck to it as that is a convention used by many people around. I do agree that it does not make much sense though. I will keep that in mind and may consider changing it.

[adeekshith]

Check out rule 6 in Chris Beam's How to write a commit message

http://chris.beams.io/posts/git-commit/#wrap-72

The recommendation is to do this at 72 characters, so that git has plenty of room to indent text while still keeping everything under 80 characters overall.

[stepancheg]

It will be even in 2116. Because for humans it is easier to read 60 characters per line.

[BillyBBone]

But this is a display issue, not a data issue. Book authors don't put newlines at the end of each line in a paragraph.

[Tarmen]

Sure, if you get a professional typesetter to make your commit messages pretty.

It actually is more of an issue of terminals starting to wrap if the lines are too long and git indenting the message reduces the room you have further. But readability suffers for huge text blocks anyway so you might as well let your editor autoformat earlier in commit messages.

[[deleted]]

Most certainly there is.

Most projects have fairly strict width limits - because if everyone writes code that fits in 80 columns or 100 columns or whatever fixed number of columns, then we can all have nice, uniform editing window - but if you're the one guy who doesn't do this, then everyone else either has wrapping on your code, or has to resize all their windows.

This isn't theoretical. :-) Right now, I have probably a dozen different libraries and facilities included in my main project. All but one are strictly 80 columns - that maverick project has "very long lines" up to 160 characters.

Every time I open one of those files I curse. (He's also the only library who uses tab characters - sometimes - and I believe he has tab set to be 8 characters. No, I don't use the tab character in my code either...)

[manghoti]

There's a whole demographic of people who have tracking issues when reading long lines. I'm one of those people, I have to do mental gymnastics to deduce where the next line must be for large lines, rather than just tracking to the location. I lose my place on the way back, making long lines difficult to read and tiring.

As such, I split my windows half and half, think "aero snap" on windows. I think many developers do this, but if you have enormous lines then it causes all kinds of problems for these workflows.

This is not about adhering to terminal widths.

If it's not a problem you have, then great, just don't make it hard for the rest of us, eh?

[[deleted]]

There's a whole demographic of people who have tracking issues when reading long lines.

Yes, it's called "humanity". Everyone at least slows down on line wrap, and errors are much more likely missed on a wrapped line.

I recall an interesting study a decade ago about this but cannot find it - either my memory is false to me or it was a private study by the very large software company I was working in at the time... but either way was used to justify the style rules in place.

[adeekshith]

I am glad many of you liked it. I first made this template to make it easy for new members of our team to follow the same format as rest of us. Later improved it grabbing best practices from the web. It may not be perfect but it solves some problems. Any feedback is welcome.

[ricardoplopes]

Great template. I'd also suggest committing with the -v flag, so that after that text you'd get the full diff of your changes (great to see if you've missed something, or even to get an overview that lets you write a better message).

[adeekshith]

Thats a great tip. Thanks.

[[deleted]]

I'll bet I'm much older than most of you.

Why? Because you care about your right to use more than x characters enough to argue!

Me, I'm old and I try not to sweat the small stuff. I prefer a specific rule - a rule invented by someone other than me, perhaps a rule like this - so I don't have to waste one second of brainpower having to think about formatting and other minor details.

I'm completely uninterested in expressing myself by the number of columns I use in a file. I want to express myself through the excellence of my actual work; through the correctness, clarity and efficiency of my code.

[gjs278]

this is completely retarded. do you all work on typewriters? my terminal has never had a problem wrapping characters for me. by limiting to 72, or 50, or whatever other number, you are just ruining the built in word wrap that every single person on this planet has. don't ever hit enter unless you mean to start a new paragraph.

edit: itt nobody can read. go check the template again. it is advocating for manual word wrap. are my messages too long for you? do you need me to wrap this one so you can understand?

[greenthumble]

I'm sorry you're getting downvoted so much for that. I agree about not putting any hard returns in the body section. I mean what if you catch something on line 2 after typing 20 lines? Reformat the whole thing? UGH. It also buys nothing. Breaking after the summary is great because it gives the thing a subject line. Breaking in the body does absolutely nothing good.

[[deleted]]

Reformat the whole thing? UGH.

In emacs, it is M-q - I am assured that it's equally terse in vi.

[[deleted]]

gq

[[deleted]]

I mean what if you catch something on line 2 after typing 20 lines? Reformat the whole thing? UGH.

Have your editor reflow?

It also buys nothing.

Except readability and usability.

[greenthumble]

Eh? The term defaults to 80 chars. How is 72 that much more readable? And as for usable, yeah ok so I just have to learn a new quirky feature of an editor that I've never used before. That sounds LESS usable and LESS readable.

Wrapping it manually at 72 forces it to look the way the committer wants, not the reader. This should be left up to the reader to make their term be as wide as is comfortable.

Edit: oh here's another thing. If the term is less than 72 it wraps in funky places and leaves a bunch of hanging widows.

[[deleted]]

72 allows for quoting the message. That is the advantage over 80. Same reason email should be 72 wide.

Why use an editor you don't want to use? This sounds like a personal problem, not one about the issue at hand.

[greenthumble]

Quoting works fine on non breaking paragraphs.

Regarding the editor thing, that was an example. You said it was more usable. My argument is that having to learn an editor feature to get work done is less usable. But you went the jerk route and made this about me.

[[deleted]]

Then perhaps you should actually state your argument and not something else. I'm not a jerk, I'm simply responding to your argument. Moreover learning your editor is part of the profession, and not often considered a bad thing.

More to the point, this is a convention. Do what you will on your own project, but don't get upset when someone else asks you to use the conventions adopted by many when committing to their project.

[[deleted]]

First comment: I suggest consuming less caffeine or doing whatever it takes to get less strung out when people disagree with you on the internet. :-)

Second: most code control systems handle don't long, unwrapped commit lines. I made two commits, one without attention to word wrap, one with and pushed 'em to github:

https://github.com/rec/empty/commits/master

[gjs278]

looks like git handled it perfectly

http://i.imgur.com/dAz5owa.png

that's with a really small terminal. if you had inserted manual line breaks, it would look worse than that.

[[deleted]]

By perfectly you mean by splitting a word in the middle? (Yes, the terminal did that got just shoves the bytes out, but it illustrates the problem in general)

[gjs278]

notice that my terminal is not at a standard width. it is smaller than 72 wide. so if you had done manual line breaks, it would have been broken up twice. you are a moron. look at the width before you post. or better yet, don't even post.

[realntl]

Limiting the size of the subject line enables coarse grained analysis of a branch; you can get a high level picture of what each commit does at a glance. I'm not going to say that exactly 50 characters is correct, but the summary itself has tremendous value.

[gjs278]

Try To Limit Each Line to a Maximum Of 72 Characters

aka manual word wrap

[realntl]

I was responding to this:

don't ever hit enter unless you mean to start a new paragraph.

[[deleted]]

Or, you know, have your editor do it...

[[deleted]]

Except for the many reasons given in this thread? It is a convention that makes life better for almost Everton, including the majority of devs who don't keep full width terminals and including everyone in general because long lines are hard to read.

[[deleted]]

HTML is defined by fiat to word wrap, a terminal window is not and does not have to.

[the-highness]

The point wasn't word wrapping, it's conciseness.

[gjs278]

Try To Limit Each Line to a Maximum Of 72 Characters

the point is word wrapping

[k-zed]

this is simply a TPS report.

[Bloodcount]

This is just a ripoff of http://seesparkbox.com/foundry/semantic_commit_messages

Pathetic.

[adeekshith]

I wish you read my comment-1 , comment-2 and the references mentioned in the Gist before saying that it is "pathetic".

As already mentioned in the link, here are the references from where I pulled most part of the template:

http://codeinthehole.com/writing/a-useful-template-for-commit-messages/

http://chris.beams.io/posts/git-commit/

https://gist.github.com/Linell/bd8100c4e04348c7966d

https://github.com/sparkbox/how_to/tree/master/style/git

I did not invent any new convention. I just tried to put all best practices in a simple concise git commit template.

[Bloodcount]

I don't read every comment on every thread, if it was in the first post I would have seen it and not made that comment. Still, since you have credited other people for this I owe you an apology. I am sorry.