Commit messages are not titles

by cocoflunchy • 11 years ago

223 167 11 years ago

Does anyone actually care whether commit messages contain a period or not? If they're lower case, title case, sentence case, it's completely irrelevant

sleepychu• 11 years ago

The problem is that if your repo maintainer is encouraging you to use a title as a commit message it implies a different level of information content. commit -m "Features Aboundin: A new wave" vs. commit -m "Added initial project structure for new wave feature."

aerique• 11 years ago

The only thing I care about is whether there's an empty line between the head and body of the (Git) commit message.

I don't care whether the lines are too long, whether they're nicely capitalized, whether they end with a dot. These are all things that tickle my OCD gland but I've learned to ignore them because it is ultimately useless and a waste of my time to get worked up about it. If the summary and description are good enough, I'm a happy man.

(I'm talking about reading others people's commit messages here. I try to make my own commit messages adhere to the scriptures as declared by his Holiness himself: https://gist.github.com/matthewhudson/1475276 (which, I now note, makes no mention of the length of the header line).)

weavejester• 11 years ago

I find it a lot easier to read a commit log when it's consistent in style.

anton_gogolev2• 11 years ago

Regardless of whether commit messages are in past or present tense, have trailing period or not, properly capitalized or not -- they are all equally unreadable with all the "Merge pull request #20552 from jamesdabbs/belongs-to-polymorphic-force-reload" junk.

jsmthrowaway3• 11 years ago

I'll hesitantly admit that I do, but not enough to blog about it. It's an unconscious indicator for me of inexperience with working with conventional Git, and very (very) often I have to intentionally ignore it for someone's benefit. However, that attitude is rooted in thinking about someone's teamwork abilities; good commit message etiquette, whether regarding periods, conventions on length and formatting, and squashing instead of merging seventeen of your test commits off a feature branch, or just general writing ability and effective communication, are all something I look for in a person.

I care more about merge commits, to be honest.

pestaa• 11 years ago

I wouldn't call this indicator so unconscious when the triggers can be so easily enumerated. Agreed wholeheartedly.

zorked• 11 years ago

Considering there are people who have heart attacks based on whether a file ends with a newline or not, commit message formatting is a hugely important topic.

Cthulhu_2• 11 years ago

That's because there's some unix commandline tools that won't work right when a file does not end with a newline.

richmarr2• 11 years ago

Sadly. In my view they're bikeshedding, hard.

GotAnyMegadeth• 11 years ago

For those who don't know what that means https://en.wikipedia.org/wiki/Parkinson's_law_of_triviality

mosselman• 11 years ago

I am glad to see your comment. I wanted to post 'Who cares?' Not about commit messages, because having nice compact descriptive messages can be useful, but mostly about the 'dot' at the end. Because seriously; 'Who cares?'

gutnor2• 11 years ago

Bikeshedding like this is useful as a team efficiency metric.

If you can't get quickly to an agreement about such a thing, or if the members of the team that didn't get their way actively rebel (or worse sabotage), you are working with a team of divas.

(note: of course developers whinge, as long as you stick with the team decisions once their are made, whinge all you want)

hamburglar• 11 years ago

What is it about our industry (or perhaps just the slice of it that hangs around HN) that makes people feel the need to spout absolutist dogma about trivial shit like whether a commit message should be a sentence or not? Jesus. Sometimes a sentence is the most useful and sometimes a very short newspaper-headline-style summary is the most useful. Why must we constantly go in search of hard rules that prevent this sort of consideration? If having to shift between styles makes commit logs too hard to read for you, maybe the commit messages aren't the problem.

crdoconnor• 11 years ago

Possibly if there were going to be a machine parsing them, but otherwise no.

4ad4• 11 years ago

What? How can you not care.

Commit messages are extremely important when trying to understand the evolution of code. And the style matters a lot, not only the content. The (Linux) style is optimised both for people and tools (e.g. grep, awk).

When reviewing code I held the commit message at a much higher standard that the code itself. Nobody passes through me with a non-perfect commit. Luckily, people quickly learn and they start writing good messages without having me to force them, because they see the value.

michaelmior3• 11 years ago

Does having a dot at the end or not affect your understanding?

plq• 11 years ago

Well, commit logs could be good complement to developer documentation, if done properly. e.g. "See <some hash range> to see how to add a new protocol to Spyne!" "See <some hash range> to see how a new statement could be added to CPython!."

But, yes, if you care this much about commit format, put structured data in commit logs using yaml or something and be done with it :)

antirez3• 11 years ago

My main point is not about dots but the way you change the content of the first line depending on how do you look at it.

ionforce6• 11 years ago

It's not LITERALLY about the period. It's about how content that contains periods tends to be written a certain way that the author doesn't care for in commit messages.

Did you really not understand that?

dang2• 11 years ago

"Please don't use uppercase for emphasis. If you want to emphasize a word or phrase, put asterisks around it and it will get italicized."

https://news.ycombinator.com/newsguidelines.html

gkya3• 11 years ago

Well his argument is not really the dot at the end, but rather whether the first line of the commit message is a title to the rest of it or whether it is a one-sentence synopsis of the changeset. Examples respectively:

  Fix layout.

  Replace proprietary grid layout w/ that of Bootstrap,
  so that it is easier to manage and use. [...]

  Substitute Bootstrap for proprietary grid.

  The proprietary grid system was abandoned for Bootstrap,
  as it will let us focus on the more peculiar stuff of the
  UI.

tsiki• 11 years ago

A lot of the people commenting on the article seem to be pretty adamant that something like this matters. Personally, I've never been confused by a period (or lack of thereof) at the end of a commit message. And if such a time comes, I'll give serious thought to whether it's worth anyone's time to teach the team to use/not use periods or whether I'm better off investing that time to teach them something more useful.

StavrosK2• 11 years ago

I was recently advised to use the "commit messages are subjects" style, but I get a pang of... something, every time I have to omit the full stop (I always type it out of habit and then press backspace).

I agree completely with Antirez, messages are not subjects or titles, and we should make them as succinct as possible, not force ourselves to write something that leads into a full-text piece only to omit the latter.

If it can fit in one line, make it fit, otherwise summarize the change as well as you can. Our goal should be to have to read the least amount of text to understand what the change is doing, and the hierarchy is: short commit message > long commit message > diff.

WalterGR2• 11 years ago

    I get a pang of... something, every time I have to omit the full stop

Good. :) One thing that's very nice about the full stop:

You know that you've read to the end of something.

In the absence of one, there's always the chance that text has been cut off

StavrosK2• 11 years ago

Cut off what? The suspense is killing me!

jsmthrowaway3• 11 years ago

When using Git's mail features -- remember, not everyone uses GitHub -- the first line of a commit is a subject line. It's good practice to just think of it that way. If you write sentences in your subject lines in e-mail, I guess, that's up to you. Don't take it from me, read the Tim Pope counterpoint, with eight extremely good reasons for concise subjects in the closing paragraph:

http://tbaggery.com/2008/04/19/a-note-about-git-commit-messa...

Strong disagree with antirez on this one. Even vim filetype gitcommit disagrees. (Try it on the "smart synopsis" example.)

voyou• 11 years ago

I don't see how this is a counterpoint. tpope says "This first line should be a concise summary of the changes introduced by the commit", and antirez says the first line should be a "synopsis of the meaning of the change operated by the commit"; these appear to be exactly the same thing.

But then, I don't understand the distinction the original post seems to be making between "titles or subjects" and "synopses." A good title or subject for a git commit is a synopsis of the changes in the commit, in the same way a good headline for a newspaper article is a synopsis of the article.

VieElm2• 11 years ago

The 50 character limit on the first line of a commit message really bugs me. I try to stay within 50 characters but sometimes I don't care. I can't always fit what I want in 50 chars and adding a second line can be too much. This is the worst kind of thing around tooling, these types of conventions, in this case because that's how Torvald's wants kernel git commits formatted. I am not committing to anything Torvald's cares about.

jsmthrowaway3• 11 years ago

The 50 character convention has nothing to do with Linus Torvalds.

brazzledazzle• 11 years ago

I've seen a lot of posts and comments about the 50 character convention but I'm not sure I've ever seen a reason for that specific number. What is the reason for that anyway?

sambe• 11 years ago

I also prefer treating them as sentences and prickle at the level of enthusiasm for no dots. In the end consistency with others is more valuable though. However, the article is entirely unconvincing to me, despite being on his side - the removal of a dot and writing succinctly are not mutually exclusive.

anton_gogolev2• 11 years ago

Is it me or the entire "Kosher Commit Messages" movement really gained traction with the widespread adoption of DVCSes?

I really cannot recall contributors obsessing that much over SVN, CVS or VSS commit messages. Now, you could change these after the fact, but still.

zamalek• 11 years ago

From a code standpoint (excluding commit messages) DVCSes tend to do a better job at expressing high quality history. As an example you have two ways to express a merging history (merge and rebase), giving the developer more tools to accurately describe what has historically happened.

This "mentality" seems to have leaked out of the machine and into the mindsets of developers. Just like learning a functional language will alter the way you think so will learning a SCM that values history (which DVCSes typically do).

zelos• 11 years ago

We used to have a Perforce changelist guideline newsletter here.

No, I'm not kidding.

jgrahamc• 11 years ago

I think the body of the commit message is way more important than the title: http://blog.jgc.org/2013/07/write-good-commit-messages.html

Cthulhu_2• 11 years ago

It really depends on the situation tbf; if you're looking for a commit or an overview of what happened, titles; if you're looking for details, especially important in the less legible languages and environments (C, the Linux kernel), body.

Actually TL;DR both are important.

antirez3• 11 years ago

Body is super important, but when you can craft a very good single line commit message, is not bad either. It is hard to find a balance but what I try to do is to reserve multi line commit messages for situations where it is appropriate to provide mode details compared to just "git show" the commit to check the actual content.

necrodawg• 11 years ago

Commit messages are like tabs and spaces. However you write them, keep them the same across your repository.

But obviously lower case, present tense, no dot, 50 char limit, and usually starting with add/fix/refactor/update/remove is the way to go. ;)

knocte2• 11 years ago

As for me, I don't care about the style at all.

What I care is about the content. And the thing I hate the most are commit messages that explain the what, but not the why! (It's the equivalent to comments in the code that explain something obvious.) To me, this kind of commit messages express the same as if there was no commit message.

callum852• 11 years ago

But if the commit message says what happened, then you don't need to read diffs to find out what happened. Reading an English sentence is easier than reading code diffs, and also you can read a bunch of sentences in list form (eg, git log).

I'm not saying you don't need to include the 'why', I'm saying there is value just in the 'what'.

As for code comments that just 'explain something obvious'... I have no problem with comments that simply summarise, in English, what the next few lines do. It means I can skim through a file just reading the comments, until I find the part I want to debug/modify/understand in more detail. Also, if you can sum up some code with a sentence then there's a good chance it makes sense, so it's a good quality check.

knocte2• 11 years ago

With the 'what' of course I don't mean 'what happened', as the latter would be actually kind of the 'why' you're making the change. So with the 'what' I mean 'what is being changed', some people just write what file are changing and what they are adding to it, explaining how the code is changing in the diff, but not why the code is changing.

As for code comments, I think you're basically wrong. If you can summarize some fragment of code under a sentence, extract that piece of code into a method and name that method in the same way you were going to write that comment; otherwise comments get outdated easily. These kind of techniques are well explained in a very good book I read a while ago, it's called "Clean Code".

VeejayRampay• 11 years ago

The first comment under the post is frankly outrageous.

This is precisely the reason why the rest of the world abhors programmers and the software community. Random strangers contributing nothing to the debate but their angry and immature bile. No wonder content creators are disabling comments one after another, why wouldn't you?

jeremiep• 11 years ago

Well, programming can be picked up by just about anyone these days, so its no wonders you get people as mature as youtube commenters in the mix.

This is what differentiate professionals from amateurs.

przemoc• 11 years ago

It always felt natural to put this dot at the end of (what antirez nicely called) commit synopsis, so AFAIR I always (or at least since I started using git and when was not forced by particular project's rules to do some other way) put it there and found advices to avoid it quite strange. The only exception (beside forgetting about full stop yet pushing to public repo, it does happen sometimes) I have is when the commit is sole version-bumping/releasing one, because then I usually go with following style

    PROJECT_NAME [v]VERSION

There are some half-broken SCM managers that always display whole commit message (sometimes even without respecting paragraphs) and then such synopsis without full stop yet followed by another sentences looks rather awful. YMMV

As some commenters here already wrote, it's not a grave matter, but it's good to have consistent style. It goes without saying, that having relatively short commit summary in one sentence separated with blank line from further details (if they are necessary) is far more important matter than the period or lack thereof, as it immensely eases groking commit log.

velco• 11 years ago

Right. Commit messages are not titles.

Commit messages ought to consist of a title, followed by an empty line and a short(-ish) summary.

seanhunter2• 11 years ago

How can anyone take the author's word on whether or not to put a full stop at the end of something when he puts a full stop at the end of the bullet points in his list? That's far worse usage than anything he's doing in the title/summary/smart synopsis. https://www.oxforddictionaries.com/words/bullet-points

phireal• 11 years ago

That link you posted says you can put fullstops at the end of lists if the elements of the list are full sentences.

seanhunter2• 11 years ago

"And resulted into this" is a full sentence now? I guess. It's not really English though.

The whole thing is serious bikeshedding in my opinion.

teh_klev• 11 years ago

How many emails or articles you see with just the subject or the title? Very little, I guess

I hate to go OT and "well actually", but, well actually this is more common that you'd think. I first learned about "subject only" emails back in 1998 and most places I've worked at use them to convey succinct email messages where there's no need for extraneous words in the body. It's a real time saver when you have a busy inbox.

I've also worked in places that "EOM" (or some variant of) their message subjects to be explicit that there's nothing in the body [0].

WRT to the remainder of the article, I don't have any strong feelings either way.

[0] http://lifehacker.com/5028808/how-eom-makes-your-email-more-...

SixSigma• 11 years ago

callmekatootie• 11 years ago

Commit messages need to convey what will happen if you merge that commit in. Plain and simple. That's all that is needed of them. Of course, you need to tag the ticket number (in case you are using Cloud based solutions like Github) but I am more interested in what the changes will do if I merge them in.

nandemo• 11 years ago

In a previous gig, we had a simple rule: there must be a ticket number with a certain format at the beginning of the commit message. A summary follows.

The ticket has pretty much all the info you need, so there's usually no need to write a very detailed commit message.

This essentially mandates tickets for every single commit, which might sound too process heavy for some people, but ticketing was part of our process anyway for other reasons (change management, compliance, etc).

In the rare event that a commit is not originated by a ticket, you can still cheat by writing a fake ticket number.

dsr_• 11 years ago

It ought to be a simple matter to start a new ticket and dump your work into it.

A la the Joel Test, your ticketing system should:

- open a new ticket on receipt of unknown email, sending back the ticket number

- treat email with a proper subject prefix as a comment on an existing ticket, adding any attached files

- easily merge two or more tickets, preserving both histories and redirecting all references to the old tickets to the new one

- maintain metadata and ACLs for metadata

- automatically re-open a ticket when a new comment or reply is received

- require a message to close a ticket

- provide summaries

- be full-text searchable

- track all history immutably

- provide a method to associate many individual reports of the same problem

jkot• 11 years ago

Commit messages could have titles :-)

Most tools only shows first line of message. Rest of the message can contain whatever you want.

stared3• 11 years ago

Dots, periods or starting with caps - it makes no difference (except for aesthetics, perhaps.) What does (or at least: did for me) is Angular-style commit messages: https://github.com/angular/angular.js/blob/master/CONTRIBUTI....

<type>(<scope>): <subject>
[...]
feat: A new feature
fix: A bug fix
docs: Documentation only changes
style: Changes that do not affect the meaning of the code (white-space, formatting, missing semi-colons, etc)
refactor: A code change that neither fixes a bug or adds a feature
perf: A code change that improves performance
test: Adding missing tests
chore: Changes to the build process or auxiliary tools and libraries such as documentation generation

There is a big difference in knowing if someone added a feature, fixed something, or did some refactoring.

4ad4• 11 years ago

Starting with caps or not makes a huge difference. It can easily break naive grep/awk. Other problems are typos and idiosyncratic spellings. Always spell-check your commit messages, it should be part of your git hooks.

emerongi• 11 years ago

By that logic we should also take into account all the other 1000s pieces of technology that can operate with text. In the end it all comes down to personal preference or the project guidelines.

planetjones• 11 years ago

I just see that as friction. Now a developer who is working on a new feature is reluctant to take opportunities to refactor incase their commit message doesn't match the "standard". Empower the developer and reduce friction to a minimum is my modus operandi.

Plus commit often and plan commits: with the example above the commit messages themselves are becoming a chore. Just make the message meaningful and link it to a JIRA issue or something. That's simple enough for me.

hahainternet2• 11 years ago

I just see that as friction. Now a developer who is working on a new feature is reluctant to take opportunities to refactor incase their commit message doesn't match the "standard". Empower the developer and reduce friction to a minimum is my modus operandi.

Honestly those commits should probably be split anyway. A commit should represent the smallest 'change' which is singificant.

kosma• 11 years ago

Now a developer who is working on a new feature is reluctant to take opportunities to refactor incase their commit message doesn't match the "standard".

Having maintained a few projects on Github, I routinely reject commits that both introduce new features and fix/refactor things. Refactoring is good, but jumping on a project and changing everything at once is a strong indicator of a lack of focus. The "fix some of everything" commits usually lack tests and documentation updates which wouldn't have been overlooked if the contributor took a step away and looked at the big picture.

overgard4• 11 years ago

Yeah, that's why I really hate rules like "all commits must have a user story attached". I'm not going to make a jira story for "function is poorly named", so if that's the rule then the code will fall to entropy.

arethuza2• 11 years ago

For some reason the fact that "feature" is abbreviated to "feat" while "refactor" which is actually longer than "feature" is left alone irritates me - which, of course, doesn't mean anything other than to demonstrate how silly this kind of argument can be!

pandler• 11 years ago

True, but "ref" is ambiguous since that abbreviation is usually used to mean "reference". "refac" or "refact" just don't roll off the tongue.

eli• 11 years ago

Every newspaper -- even ones that mostly use AP style -- has its own slightly different style guide. I don't think that proves style guides are pointless.

antirez3• 11 years ago

Hep, that's very good. I'm trying to do this recently, it is very hard btw unless you organize different topics beforehand, but then it is easy to escape since I often try to do something like "Submodule: ...." because later to merge just a single feature is simpler because commits are "tagged" with the name of the feature or module.

stared3• 11 years ago

I do have problems with "(<scope>)", but I don't treat commit messages as statements defining code structure, but as hints of what I did.

(In any case, I don't use Angular-style commits for all projects. But learning about them was a small (but important) step in reducing complexity, vide http://www.johndcook.com/blog/2015/06/18/most-important-skil...)

braythwayt2• 11 years ago

Whenever I see a convention like this, I think to myself, “There is another data model being serialized into text.”

WalterGR2• 11 years ago

So very true. And I struggle with this. "Why should I write something out when tools could do it for me? Isn't me specifying it, then, just me being overly verbose?" But tools often don't - and may never.

I'm curious:

In any tool for any revision control system ever: in a list of commits, are the commit messages augmented with something useful beyond the basics? ("Basics" being e.g. the first 'n' characters of the human-provided commit message, a revision identifier, a timestamp, and a username.)

stared3• 11 years ago

Not exactly. The actual commit content is in the code difference. Code message is just some kind of human-readable abstract, or at least - a hit of what was changed.

There is a big deal of subjectivity (e.g. what is a bug, and what is a feature) but (as with any comments in the code) it is nice to see at least what was intended (e.g. someone wanted to position a misaligned button, or added it, or improved its visuals or optimized its click from O(n!) to O(1), ...).

jonahx• 11 years ago

Great observation, though it's not a bad thing, necessarily (assuming you were even implying that it was).

In fact, it could be a very good thing, especially if the alternative is, eg, dropdowns for type and scope, and a separate popup for editing or adding new ones, and so on.

Having the data model loosely encoded as text, and understood only by convention among humans, who can then improvise changes to that model in exceptional cases, relying on other humans to make sense of those changes even though they are "outside" the agreed-upon model, is sometimes exactly what you want.

Also, as UI for input, text is often the fastest and most efficient -- again, just what you want. Of course, you could always do string validation on the text input to enforce your model, so this can be considered an orthogonal point.

And these considerations don't even touch upon the increased complexity and maintenance costs that your tool itself (in this case, git) will incur if it takes on the burden of maintaining the data model explicitly.

Bahamut• 11 years ago

One really nice side-effect is that these commits can be used to autogenerate changelogs, which is what the Angular team does.

hasteur• 11 years ago

While I commend the poster's ideals, the method only works in the glass cathedrals model of development. One in which no commit gets made without having followed the process from inception, through requirements gathering, through unpressured development, through appropriate and thorough QA/code review, and deployment. In the street market bazzar you're left with thousands of micro commits that you don't have time to sit down and create an illuminated manuscript page for each commit explaining it's small description, and it's naritive history.

chrisan• 11 years ago

I really like bitbucket and JIRA for this in a business use case.

We use the format "JIRA-XXX commit message/title/synopsis/whatever you wish to call it" where JIRA is our project name in JIRA and XXX is the ticket number. Bitbucket then can turn that into a link to your JIRA project

All of the who/what/why is already in the JIRA ticket as more often than not there are non-coders who have input/insight around the issue. When I am looking at the commit log I see a brief summary and if I need more details I can go to JIRA and get the full history with screenshots, designs, reproducible steps, business cases, etc.

Another side effect of this is, when someone is searching in JIRA and finds a ticket they can easily see all of the commits related to that ticket. This also works with Github

The commit becomes simply the "how" "JIRA-XXX brief desc" was implemented

ascagnel_• 11 years ago

The issue with this is that, over the course of development, the comments on a given JIRA ticket will start to cover QA and release steps, and they drive down the signal-to-noise ratio.

ajuc2• 11 years ago

Never had problem with this. Usually people add separate linked task for release (and specification).

jlouis2• 11 years ago

I have the following in my git config for handling these kinds of discussions:

    [jlouis@lady-of-pain ~]$ cat .gitconfig | grep phk
	phk = commit -a -m 'upd'

erikb2• 11 years ago

Does phk mean what I think it means? It's definitely funny and I'd definitely decline all your pull requests, but in company work it really doesn't matter because most people don't look into the history anyway. So yeah, it's probably a productivity tip.

jlouis2• 11 years ago

It pays eternal homage to a toy-repository by phk in which that commit message occurs. I found it more fun than `git yolo`. And easier to type as well.

The other reason I have it is that when you are first building up a piece of software, you may want to snapshot it now and then, but you don't care too much for the archeology because things are still not working. Once you reach something which seems to work, you squash everything down and cut your first release with a meaningful commit.

Traut• 11 years ago

why is this even important?

ionforce6• 11 years ago

Because commit messages are important.

tempodox• 11 years ago

It seems obvious that inside any given organisation, it makes sense to have a convention regarding the form of commit messages, so you know how to look for certain things.

However, pretending there is a one-size-fits-all rule is taking it too far.

mkawia• 11 years ago

my commits are not only titles they are milestones , I have lolcommits installed and pose for the selfie and everything.

Could be because of I am new to git

m0skit02• 11 years ago

We use Redmine and just put the relevant issue number and the title of the issue. If more information is needed, you can go to Redmine to check more details or how to reproduce.

pdpi• 11 years ago

I prefer the next step over: Branch is named after the ticket and a short description of what the branch does, commit messages just talk about the contents of the commit itself.

m0skit02• 11 years ago

We actually don't make a branch for each ticket because we need to expose the repositories to outside and so we use Gitolite, and having to reconfigure branch permissions each time... Ain't nobody got time for that.

kashyapc• 11 years ago

Speaking of Git commit messages, it's worth pointing out this wiki[1], written and reviewed by some long time open source contributors. It's a bit verbose, but rewarding to the patient reader.

On writing Git commit subject lines, I've come to appreciate why the imperative mood is nicer (as opposed to the and indicative mood). Some related reasoning here[2].

[1] https://wiki.openstack.org/wiki/GitCommitMessages [2] http://chris.beams.io/posts/git-commit/

js2• 11 years ago

  Add comment strongly agreeing with parent

  The links in the parent comment are to documents which are
  prescriptive, based on hard-earned experience, and provide
  well-reasoned justifications for how and why to format commit
  messages, along with examples of projects which do so.

  I wish the parent comment were at the top of the page, but I can
  provide only a single upvote. This comment is to provide more
  exposure than an upvote alone, and so that I can find it my HN
  history.

gkya3• 11 years ago

- http://orgmode.org/ (or Evernote, this-pad, that-pad...)

- https://en.wikipedia.org/wiki/Bookmark_%28World_Wide_Web%29

- Direct link to parent comment: https://news.ycombinator.com/item?id=9764039

doe88• 11 years ago

I think the two most important rules are:

1- The first line should give a good description of the commit

2- Avoid long lines (reading truncated commit messages is painful)

Other than that I think it's all common sense/good judgment and I'm not attached to a particular writing style or kind of sentences one should make.

zvrba• 11 years ago

How about: if your message doesn't fit into a single sentence, the commit is too big. Split it. If it's a huge architectural change merged from another branch, describe it in a separate document referenced in the message.

scottjad• 11 years ago

An option for git or magit that would automatically look at recent commits and maybe capitalize or add a period to my commit message so that it is consistent with the majority of the commits for the project would be nice.

Does something like that exist?

prattmic• 11 years ago

I don't know if someone has already written one, but a commit-msg hook could certainly achieve this.

http://git-scm.com/docs/githooks

LoSboccacc• 11 years ago

Linus on good git comments: https://gist.github.com/matthewhudson/1475276

The first line is special for a reason, it makes shortlog clean and clear.

emodendroket• 11 years ago

Way too much energy to expend on worrying about this.

I put Github issue numbers into my commits because I use Github. Anything is fine if you're consistent.

buster2• 11 years ago

Regardless of my opinion about this subject, i always find it good to see when people try to think out of the box. Nowadays most people just follow what is the current hype:

yeah, let's do semver! And it HAS TO BE react, agile and also it must be in Git, because... yeah, because what? Did you as a developer really think why you are following a certain practice and if it is beneficial to your project at hand? Most people don't. They just do what John Doe posts on his hipster blog about Web3.0.

minot• 11 years ago

If you join a team project, you have to follow the team convention. It is not necessary to put dbo. in front of table names in SQL server. Yes, you can use .PHP instead of .INC for class files. No, C# will compile just fine if you indent with four spaces or eight spaces instead of a tab.

However, when you are working in a team, you follow the convention of the team. Or change the convention so the team is on the same page.

buster2• 11 years ago

The point is not the existence of conventions but the correct and wise application of them as opposed to just "let's do what the internet blogs about!".

hobs• 11 years ago

It is not necessary to put dbo. in front of table names in SQL server.

Depending on default schema, it definitely can have performance considerations on compilation.

Maybe some of those team conventions are actually based on real world things.

From: https://msdn.microsoft.com/en-us/library/dd283095%28v=sql.10...

SELECT * FROM Table1

Will assess the following statement first: SELECT * FROM <defaultschema>.Table1

If it cannot find the object, the server will assess the following statement: SELECT * FROM dbo.Table1.

The assessment process can be improved by using either the fully qualified name or the DEFAULT_SCHEMA option described earlier. By setting a value for DEFAULT_SCHEMA for the user, the server will check the DEFAULT_SCHEMA first, removing an unnecessary ownership checking process. This can improve performance considerably on heavily utilized systems.

ionforce6• 11 years ago

Critical thinking will never be out of style, no matter how much people try.

P4u1• 11 years ago

At our company we use a svn hook with Jira, so all commit messages must contain a valid Jira issue ID which contains a detailed explanation of the commit itself. So our messages are always like: PROJ-0001 I did this. IMO does the job and is much easier for the developers.

peterwwillis• 11 years ago

Fuck it. From now on, all my first lines will be UTF-8 emoji.

strictfp3• 11 years ago

Oh god, another commit message discussion.

It's funny how the ones who contribute the least to the functionality have the most outspoken opinions on commit messages. Perhaps it's easier to be puritan when you only handle trivial code changes.

I prefer productive people with messy commit messages over pedantic people with meticolous commit messages any day.

The picky ones usually refuse to touch anything surrounding their particular feature and end up increasing code complexity with every commit, whereas the productive people massage the code into the best possible state as they go along.

xiaq• 11 years ago

It's funny how the ones who contribute the least to the functionality have the most outspoken opinions on commit messages. Perhaps it's easier to be puritan when you only handle trivial code changes.

According to GitHub, this guy is the author of Redis and he has made 3659 commits to the repository. Call that trivial code changes.

strictfp3• 11 years ago

I'm not criticizing Antirez, he seems to be on the recieving end.

ionforce6• 11 years ago

I don't understand how you could possibly tolerate messy commit messages. It's as if you've never had to do a code investigation/audit ever, heaven forbid you do.

GrinningFool• 11 years ago

I don't think that's a fair statement, at least based on my own experience. When I'm investigating how code arrived at a certain state, I'm looking primarily at the code.

The commit messages are nice as indicators of intent, but I don't rely on them. The real change is in the code, not what somebody remembered to write in a summary of the change.

strictfp3• 11 years ago

Well, I don't tolerate just anything. But I much rather have "fixed fs race" than "merged a13b1z: <issue 14365><subsystem core><signoff:dave> changed fs_handle.lock to use blargh_lock_45"

overgard4• 11 years ago

I don't understand how you could possibly tolerate messy commit messages.

I mean, it's pretty easy. You just like, tolerate it.

I'm sure there are contexts where strict rules are important, but in my experience most of the time fussy commit message rules are put in place it's because someone has reimagined themselves as the gordon ramsey of code and the people rolling their eyes don't want to get entrenched in a political battle where they're against "professionalism", so they just deal with it, or someone with mild OCD is inflicting it on everyone else. (I know I'm being harsh and I'm writing this tongue in cheek, I don't really think that badly of people that are super fussy about these things, but I've rarely seen any actual utility come from strict commit rules).

maxehmookau• 11 years ago

I'm waiting for the 'Commit messages considered harmful' blog post.

silveira• 11 years ago

This is what I'm using now: http://seesparkbox.com/foundry/semantic_commit_messages.

chore: add Oyster build script

docs: explain hat wobble

feat: add beta sequence

fix: remove broken confirmation message

refactor: share logic between 4d3d3d3 and flarhgunnstow

style: convert tabs to spaces

test: ensure Tayne retains clothing

theVirginian• 11 years ago

Why is it that programmers invariably state their opinions as if they were facts.

JoeAltmaier4• 11 years ago

Qualifying an argument weakens it. And makes it less concise. Note: I could have said "I think that usually qualifying an argument tends to weaken it in the eyes of the reader". Which is better in a text discussion?

overgard4• 11 years ago

I think people tend to overthink this. The only thing I need from a commit message is what you did and why you did it. (One might be implicit from the other). If there's more than that, you might be committing too much at once. People hardly ever go over commit history unless something got fucked up, and then those are the things you're interested in. Whenever people get OCD about the form or rules I cringe.

JoeAltmaier4• 11 years ago

As others have observed, these comments are used for auto-documentation, for reporting, and for merge requests. Its handy to be able to categorize them, to schedule and organize these activities.

overgard4• 11 years ago

I feel like things like "auto documentation" and "automated reporting" are code words for "things that superficially sound useful that in reality no human should ever use to make an actual decision". So in that context, well formed commit messages are very important for supporting bureaucratic nonsense. My feeling is that if you want to publish a change log, you should do that by hand while keeping the intended audience in mind, and if you want to review the performance of people, "metrics" are extremely game-able and instead the work should be considered as a whole.

macu• 11 years ago

I perceive the condensed sentence fragment (as requested for Angular) as a conceptual gist, which is all it really is (a few words to suggest the bigger picture), not a title (each commit is identified by its hash).

fapjacks• 11 years ago

I ALWAYS commit message like this:

For example like this:

"refactor: tightened for() loop in networking code"

"added: feature #134"

"removed: debug cruft"

"fixed: one-off bug in string parser"

nnoitra• 11 years ago

What's your blog theme? So cool and minimalistic.

Commit messages are not titles

Related Stories