11 ms·

Commit messages are not titles

223 points by cocoflunchy 11y ago

BillinghamJ 11y 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 11y 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 11y 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 https://gist.github.com/matthewhudson/1475276 (which, I now note, makes no mention of the length of the header line).)
- weavejester 11y ago
  I find it a lot easier to read a commit log when it's consistent in style.
  - anton_gogolev 11y 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.
    - harperlee 11y ago
      Yeah, that's something that I never understood. The most important information is not that this is a merge, but the intent of the branch. You can give extra detail in the extended part, but the title should not be just referencing the way in which those changes found their way to the branch, and not what they do as in the rest of commits...
      - gknoy 11y ago
        I believe Github lets one add extended commit messages for merge commits. Most of us (including me) tend to ignore that and use the autogenerated one. It'd be nice if we had an easy option to automatically include the PR's description (first comment) as the merge commit's message.
    - djur 11y ago
      `git log --no-merges` saved me a lot of headaches after switching to a pull request-based review model at work.
- jsmthrowaway 11y 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 11y ago
    I wouldn't call this indicator so unconscious when the triggers can be so easily enumerated. Agreed wholeheartedly.
- zorked 11y 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_ 11y ago
    That's because there's some unix commandline tools that won't work right when a file does not end with a newline.
    - eropple 11y ago
      For serious. For just one example, `cat` doesn't act as expected without a trailing newline. You end up with stuff like <(echo) to space things out and it's really bogus.
    - jodrellblank 11y ago
      lol. You'd think if "it's open source you can fix it yourself" worked as an ideology, its heartland would be Unix commandline text processing tools.
      - gkya 11y ago
        > "If it's open source you can fix it yourself, given that it is not standardised somehow, and that you have time to spare, and that you have the skills and knowhow to do it or that you possess the financial resources to hire some developers to do it for you. FTFY.
    - the_why_of_y 11y ago
      Actually the ISO C99 language standard requires that every source file ends with a newline (§5.1.1.2, 2.): "A source file that is not empty shall end in a new-line character [...]" So if your C implementation doesn't complain about source files that don't end with a newline, you're unknowingly relying on a language extension.
  - GrumpyBen 11y ago
    Try to use cat with a file that doesn't end with a newline.
- richmarr 11y ago
  Sadly. In my view they're bikeshedding, hard.
  - GotAnyMegadeth 11y ago
    For those who don't know what that means https://en.wikipedia.org/wiki/Parkinson's_law_of_triviality https://en.wikipedia.org/wiki/Parkinson's_law_of_triviality
    - steveklabnik 11y ago
      See also http://bikeshed.org/ http://bikeshed.org/ (make sure to hit F5 a few times)
  - mosselman 11y 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?'
    - deleted 11y ago
      [deleted]
  - gutnor 11y 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)
    - falcolas 11y ago
      > If you can't get quickly to an agreement about such a thing ... you are working with a team of divas. Or you're working on such a trivial problem that it should have been given to an individual, not a team.
- crdoconnor 11y ago
  Possibly if there were going to be a machine parsing them, but otherwise no.
- 4ad 11y 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.
  - deleted 11y ago
    [deleted]
  - michaelmior 11y ago
    Does having a dot at the end or not affect your understanding?
    - kolme 11y ago
      It does affect readability! That's the reason we have punctuation rules in human languages. Maybe it doesn't have any effect when reviewing _one_ commit message, but when you're reading a list of hundreds, or thousands of them, it does have a huge impact. This messages are meant to be consumed by humans, as in natural language. So it should respect the rules / conventions of that natural language. The same way when we write code we should respect the coding style of the code base we are working on, we should respect the style conventions of the natural languages. Because of the same reasons.
      - JoeAltmaier 11y ago
        Its defensible to adopt an abbreviated style suitable for the context of oneliner commits in a long report. Nobody uses natural language when creating other textual reports like that - e.g. log messages, checkbook register, ships' log. They all have an encoded style unrelated to natural language.
      - 4ad 11y ago
        Also, even if it doesn't affect you, that is completely irrelevant for the project. A project should be oblivious to any one developer's preferences. Successful software projects thrive on conventions that affect the whole project. People do what's implicitly or explicitly agreed on, a person can't just ignore rules he doesn't see the value of. People generally accept that when it's about coding conventions. Commit messages are just another convention. The rules are not arbitrary, in fact, if you read the Linux commit style guide, it will try to explain the value of the conventions. If you still don't get it, or you disagree, too bad. Conventions are much more important that individual opinions. If you prefer spaces, you'd better start using tabs when you want to contribute to the Linux kernel. (By you I meant, of course, some abstract person who doesn't see the value of certain rules, not kolme who I am responding to).
- plq 11y 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 :)
- antirez 11y 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.
- ionforce 11y 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?
  - dang 11y 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 https://news.ycombinator.com/newsguidelines.html
    - ionforce 11y ago
      I didn't know that so I'm going to test it here.
      - dang 11y ago
        Just don't ask me how to get a literal asterisk in there.
        cpach 11y ago
        Haha! :D
    - Flenser 11y ago
      Could HN's post and reply forms be changed so that if you type a word in uppercase in it, that message appears beside/under the form?
- gkya 11y 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: 1) Fix layout. Replace proprietary grid layout w/ that of Bootstrap, so that it is easier to manage and use. [...] 2) 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 11y 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.
StavrosK 11y 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.
- WalterGR 11y 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
  - StavrosK 11y ago
    Cut off what? The suspense is killing me!
jsmthrowaway 11y 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-messages.html 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 11y 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.
VieElm 11y 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.
- jsmthrowaway 11y ago
  The 50 character convention has nothing to do with Linus Torvalds.
  - brazzledazzle 11y 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?
    - mikekchar 11y ago
      It appears to originate with Tim Pope: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html http://tbaggery.com/2008/04/19/a-note-about-git-commit-messa... Reading between the lines, it seems that the 50 character limit is to accommodate commands like "git log --pretty=oneline" and "git rebase --interactive" on an 80 column terminal. He also recommends 72 columns for any subsequent text because git makes a left margin of 4 characters and it looks balanced if you also have a right margin of 4 characters (80 - 8 = 72). As someone who actually uses an 80 column terminal, I appreciate this practice. Probably younger people with good eyes won't be able to understand the reasoning behind it ;-)
      - VieElm 11y ago
        > Probably younger people with good eyes won't be able to understand the reasoning behind it ;-) Serious question, have you tried reading glasses? You don't have to just deal with bad eyes as you age, you can wear reading glasses. This what I do now.
sambe 11y 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_gogolev 11y 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 11y 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 11y ago
  We used to have a Perforce changelist guideline newsletter here. No, I'm not kidding.
jgrahamc 11y 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 http://blog.jgc.org/2013/07/write-good-commit-messages.html
- Cthulhu_ 11y 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.
- antirez 11y 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 11y 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. ;)
knocte 11y 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.
- antocv 11y ago
  But it is really hard. I think 80% of the commits in this current project have the word "fix" in it. I hate that word. Doesnt say or mean anything anymore, hardly ever did. To improve a teams or organizations commit messages, perhaps we should instill an organization/team-wide ban on certain words, such as fix, and bug. How can more than 50% of a development project be bugs and fixes? Dafuq.
- callum85 11y 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.
  - knocte 11y 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 11y 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 11y 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 11y 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 11y 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.
seanhunter 11y 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 https://www.oxforddictionaries.com/words/bullet-points
- phireal 11y ago
  That link you posted says you can put fullstops at the end of lists if the elements of the list are full sentences.
  - seanhunter 11y 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.
    - Retra 11y ago
      "Sentence" is a highly debated linguistic construct with no clear rules for what does or doesn't apply. You don't think that's a sentence? So what?
teh_klev 11y 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-efficient http://lifehacker.com/5028808/how-eom-makes-your-email-more-...
- SixSigma 11y ago
  NT
callmekatootie 11y 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 11y 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_ 11y 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 11y ago
Commit messages could have titles :-) Most tools only shows first line of message. Rest of the message can contain whatever you want.
stared 11y 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/CONTRIBUTING.md#commit 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.
- 4ad 11y 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 11y 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.
    - 4ad 11y ago
      > we should also take into account all the other 1000s pieces of technology that can operate with text Yes, it called the Unix philosophy, good programs do it.
- planetjones 11y 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.
hasteur 11y 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 11y 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_ 11y 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.
  - ajuc 11y ago
    Never had problem with this. Usually people add separate linked task for release (and specification).
jlouis 11y 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'
- erikb 11y 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.
  - jlouis 11y 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.
    - erikb 11y ago
      Yeah in a feature branch it's also reasonable. `git yolo` is also nice.
Traut 11y ago
why is this even important?
- ionforce 11y ago
  Because commit messages are important.
tempodox 11y 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 11y 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
m0skit0 11y 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 11y 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.
  - m0skit0 11y 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 11y 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 https://wiki.openstack.org/wiki/GitCommitMessages [2] http://chris.beams.io/posts/git-commit/ http://chris.beams.io/posts/git-commit/
- js2 11y 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.
  - gkya 11y ago
    - http://orgmode.org/ http://orgmode.org/ (or Evernote, this-pad, that-pad...) - https://en.wikipedia.org/wiki/Bookmark_%28World_Wide_Web%29 https://en.wikipedia.org/wiki/Bookmark_%28World_Wide_Web%29 - Direct link to parent comment: https://news.ycombinator.com/item?id=9764039 https://news.ycombinator.com/item?id=9764039
doe88 11y 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 11y 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 11y 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 11y 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 http://git-scm.com/docs/githooks
LoSboccacc 11y ago
Linus on good git comments: https://gist.github.com/matthewhudson/1475276 https://gist.github.com/matthewhudson/1475276 The first line is special for a reason, it makes shortlog clean and clear.
emodendroket 11y 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.
buster 11y 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 11y 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.
  - buster 11y 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 11y 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.100%29.aspx 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.
P4u1 11y 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 11y ago
Fuck it. From now on, all my first lines will be UTF-8 emoji.
strictfp 11y 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 11y 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.
  - strictfp 11y ago
    I'm not criticizing Antirez, he seems to be on the recieving end.
- ionforce 11y 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 11y 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.
    - 11y ago
maxehmookau 11y ago
I'm waiting for the 'Commit messages considered harmful' blog post.
silveira 11y ago
This is what I'm using now: http://seesparkbox.com/foundry/semantic_commit_messages 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 11y ago
Why is it that programmers invariably state their opinions as if they were facts.
- JoeAltmaier 11y 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?
overgard 11y 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.
- JoeAltmaier 11y 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.
  - overgard 11y 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.
    - JoeAltmaier 11y ago
      You don't read release notes?
macu 11y 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 11y ago
I ALWAYS commit message like this: <action>: <brief explanation> 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 11y ago
What's your blog theme? So cool and minimalistic.

223 points by cocoflunchy 11y 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 11y 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 11y 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 https://gist.github.com/matthewhudson/1475276 (which, I now note, makes no mention of the length of the header line).)
weavejester 11y ago
I find it a lot easier to read a commit log when it's consistent in style.
- anton_gogolev 11y 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.
  - harperlee 11y ago
    Yeah, that's something that I never understood. The most important information is not that this is a merge, but the intent of the branch. You can give extra detail in the extended part, but the title should not be just referencing the way in which those changes found their way to the branch, and not what they do as in the rest of commits...
    - gknoy 11y ago
      I believe Github lets one add extended commit messages for merge commits. Most of us (including me) tend to ignore that and use the autogenerated one. It'd be nice if we had an easy option to automatically include the PR's description (first comment) as the merge commit's message.
  - djur 11y ago
    `git log --no-merges` saved me a lot of headaches after switching to a pull request-based review model at work.
jsmthrowaway 11y 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 11y ago
  I wouldn't call this indicator so unconscious when the triggers can be so easily enumerated. Agreed wholeheartedly.
zorked 11y 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_ 11y ago
  That's because there's some unix commandline tools that won't work right when a file does not end with a newline.
  - eropple 11y ago
    For serious. For just one example, `cat` doesn't act as expected without a trailing newline. You end up with stuff like <(echo) to space things out and it's really bogus.
  - jodrellblank 11y ago
    lol. You'd think if "it's open source you can fix it yourself" worked as an ideology, its heartland would be Unix commandline text processing tools.
    - gkya 11y ago
      > "If it's open source you can fix it yourself, given that it is not standardised somehow, and that you have time to spare, and that you have the skills and knowhow to do it or that you possess the financial resources to hire some developers to do it for you. FTFY.
  - the_why_of_y 11y ago
    Actually the ISO C99 language standard requires that every source file ends with a newline (§5.1.1.2, 2.): "A source file that is not empty shall end in a new-line character [...]" So if your C implementation doesn't complain about source files that don't end with a newline, you're unknowingly relying on a language extension.
- GrumpyBen 11y ago
  Try to use cat with a file that doesn't end with a newline.
richmarr 11y ago
Sadly. In my view they're bikeshedding, hard.
- GotAnyMegadeth 11y ago
  For those who don't know what that means https://en.wikipedia.org/wiki/Parkinson's_law_of_triviality https://en.wikipedia.org/wiki/Parkinson's_law_of_triviality
  - steveklabnik 11y ago
    See also http://bikeshed.org/ http://bikeshed.org/ (make sure to hit F5 a few times)
- mosselman 11y 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?'
  - deleted 11y ago
    [deleted]
- gutnor 11y 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)
  - falcolas 11y ago
    > If you can't get quickly to an agreement about such a thing ... you are working with a team of divas. Or you're working on such a trivial problem that it should have been given to an individual, not a team.
crdoconnor 11y ago
Possibly if there were going to be a machine parsing them, but otherwise no.
4ad 11y 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.
- deleted 11y ago
  [deleted]
- michaelmior 11y ago
  Does having a dot at the end or not affect your understanding?
  - kolme 11y ago
    It does affect readability! That's the reason we have punctuation rules in human languages. Maybe it doesn't have any effect when reviewing _one_ commit message, but when you're reading a list of hundreds, or thousands of them, it does have a huge impact. This messages are meant to be consumed by humans, as in natural language. So it should respect the rules / conventions of that natural language. The same way when we write code we should respect the coding style of the code base we are working on, we should respect the style conventions of the natural languages. Because of the same reasons.
    - JoeAltmaier 11y ago
      Its defensible to adopt an abbreviated style suitable for the context of oneliner commits in a long report. Nobody uses natural language when creating other textual reports like that - e.g. log messages, checkbook register, ships' log. They all have an encoded style unrelated to natural language.
    - 4ad 11y ago
      Also, even if it doesn't affect you, that is completely irrelevant for the project. A project should be oblivious to any one developer's preferences. Successful software projects thrive on conventions that affect the whole project. People do what's implicitly or explicitly agreed on, a person can't just ignore rules he doesn't see the value of. People generally accept that when it's about coding conventions. Commit messages are just another convention. The rules are not arbitrary, in fact, if you read the Linux commit style guide, it will try to explain the value of the conventions. If you still don't get it, or you disagree, too bad. Conventions are much more important that individual opinions. If you prefer spaces, you'd better start using tabs when you want to contribute to the Linux kernel. (By you I meant, of course, some abstract person who doesn't see the value of certain rules, not kolme who I am responding to).
plq 11y 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 :)
antirez 11y 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.
ionforce 11y 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?
- dang 11y 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 https://news.ycombinator.com/newsguidelines.html
  - ionforce 11y ago
    I didn't know that so I'm going to test it here.
    - dang 11y ago
      Just don't ask me how to get a literal asterisk in there.
      - cpach 11y ago
        Haha! :D
  - Flenser 11y ago
    Could HN's post and reply forms be changed so that if you type a word in uppercase in it, that message appears beside/under the form?
gkya 11y 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: 1) Fix layout. Replace proprietary grid layout w/ that of Bootstrap, so that it is easier to manage and use. [...] 2) 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 11y 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.

StavrosK 11y 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.

WalterGR 11y 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
- StavrosK 11y ago
  Cut off what? The suspense is killing me!

jsmthrowaway 11y 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-messages.html 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 11y 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.

VieElm 11y 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.

jsmthrowaway 11y ago
The 50 character convention has nothing to do with Linus Torvalds.
- brazzledazzle 11y 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?
  - mikekchar 11y ago
    It appears to originate with Tim Pope: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html http://tbaggery.com/2008/04/19/a-note-about-git-commit-messa... Reading between the lines, it seems that the 50 character limit is to accommodate commands like "git log --pretty=oneline" and "git rebase --interactive" on an 80 column terminal. He also recommends 72 columns for any subsequent text because git makes a left margin of 4 characters and it looks balanced if you also have a right margin of 4 characters (80 - 8 = 72). As someone who actually uses an 80 column terminal, I appreciate this practice. Probably younger people with good eyes won't be able to understand the reasoning behind it ;-)
    - VieElm 11y ago
      > Probably younger people with good eyes won't be able to understand the reasoning behind it ;-) Serious question, have you tried reading glasses? You don't have to just deal with bad eyes as you age, you can wear reading glasses. This what I do now.

sambe 11y 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_gogolev 11y 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 11y 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 11y ago
We used to have a Perforce changelist guideline newsletter here. No, I'm not kidding.

jgrahamc 11y 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 http://blog.jgc.org/2013/07/write-good-commit-messages.html

Cthulhu_ 11y 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.
antirez 11y 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 11y 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. ;)

knocte 11y 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.

antocv 11y ago
But it is really hard. I think 80% of the commits in this current project have the word "fix" in it. I hate that word. Doesnt say or mean anything anymore, hardly ever did. To improve a teams or organizations commit messages, perhaps we should instill an organization/team-wide ban on certain words, such as fix, and bug. How can more than 50% of a development project be bugs and fixes? Dafuq.
callum85 11y 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.
- knocte 11y 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 11y 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 11y 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 11y 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 11y 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.

seanhunter 11y 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 https://www.oxforddictionaries.com/words/bullet-points

phireal 11y ago
That link you posted says you can put fullstops at the end of lists if the elements of the list are full sentences.
- seanhunter 11y 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.
  - Retra 11y ago
    "Sentence" is a highly debated linguistic construct with no clear rules for what does or doesn't apply. You don't think that's a sentence? So what?

teh_klev 11y 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-efficient http://lifehacker.com/5028808/how-eom-makes-your-email-more-...

SixSigma 11y ago
NT

callmekatootie 11y 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 11y 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_ 11y 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 11y ago

Commit messages could have titles :-) Most tools only shows first line of message. Rest of the message can contain whatever you want.

stared 11y 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/CONTRIBUTING.md#commit 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.

4ad 11y 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 11y 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.
  - 4ad 11y ago
    > we should also take into account all the other 1000s pieces of technology that can operate with text Yes, it called the Unix philosophy, good programs do it.
planetjones 11y 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.

hasteur 11y 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 11y 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_ 11y 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.
- ajuc 11y ago
  Never had problem with this. Usually people add separate linked task for release (and specification).

jlouis 11y 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'

erikb 11y 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.
- jlouis 11y 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.
  - erikb 11y ago
    Yeah in a feature branch it's also reasonable. `git yolo` is also nice.

Traut 11y ago

why is this even important?

ionforce 11y ago
Because commit messages are important.

tempodox 11y 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 11y 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

m0skit0 11y 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 11y 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.
- m0skit0 11y 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 11y 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 https://wiki.openstack.org/wiki/GitCommitMessages [2] http://chris.beams.io/posts/git-commit/ http://chris.beams.io/posts/git-commit/

js2 11y 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.
- gkya 11y ago
  - http://orgmode.org/ http://orgmode.org/ (or Evernote, this-pad, that-pad...) - https://en.wikipedia.org/wiki/Bookmark_%28World_Wide_Web%29 https://en.wikipedia.org/wiki/Bookmark_%28World_Wide_Web%29 - Direct link to parent comment: https://news.ycombinator.com/item?id=9764039 https://news.ycombinator.com/item?id=9764039

doe88 11y 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 11y 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 11y 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 11y 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 http://git-scm.com/docs/githooks

LoSboccacc 11y ago

Linus on good git comments: https://gist.github.com/matthewhudson/1475276 https://gist.github.com/matthewhudson/1475276 The first line is special for a reason, it makes shortlog clean and clear.

emodendroket 11y 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.

buster 11y 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 11y 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.
- buster 11y 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 11y 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.100%29.aspx 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.

P4u1 11y 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 11y ago

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

strictfp 11y 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 11y 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.
- strictfp 11y ago
  I'm not criticizing Antirez, he seems to be on the recieving end.
ionforce 11y 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 11y 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.
  - 11y ago

maxehmookau 11y ago

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

silveira 11y ago

This is what I'm using now: http://seesparkbox.com/foundry/semantic_commit_messages 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 11y ago

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

JoeAltmaier 11y 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?

overgard 11y 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.

JoeAltmaier 11y 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.
- overgard 11y 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.
  - JoeAltmaier 11y ago
    You don't read release notes?

macu 11y 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 11y ago

I ALWAYS commit message like this: <action>: <brief explanation> 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 11y ago

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