1. 44

  2. 30

    Another reason to write a commit message is that it forces you to think about what you’re actually committing. Not that you haven’t though about it before, of course, but I find that writing it down as a clear summary often helps spotting flaws, limitations, oversights, or other problems in my approach. I frequently discover issues while writing the commit message and then promptly fix them – issues I perhaps would have found/fixed later, but certainly not during git commit -am update.

    IMHO this aspect should perhaps be highlighted more, as it has less of a “delayed gratification” aspect to it, and helps people write better code in the now.

    Applicable quote from Dennis Ritchie on the “BUGS” section in manpages:

    Our habit of trying to document bugs and limitations visibly was enormously useful to the system. As we put out each edition, the presence of these sections shamed us into fixing innumerable things rather than exhibiting them in public. I remember clearly adding or editing many of these sections, then saying to myself “I can’t write this,” and fixing the code instead.

    1. 1

      I do love the commit message style popularized by Pieter Hintjens (of ZeroMQ).

      Every message has at least two lines. The first line starts “Problem:”, and describes in shorthand what problem is being solved. Not “there was a bug” but something like you’d see as an issue tracker’s subject line. Often that might be a problem that business facing people might see.

      “Lag on summary page load”

      “Page count misleading”

      “Memory usage too high”

      “Can’t see a process overview”

      The second line begins “Solution:” and begins to explain about why some decisions were made, what the code is doing, and how the code in the commit solves that problem. Any subsequent lines/paragraphs are added as readability dictates.

      Most often when I’m looking at an old commit, I don’t particularly care about the commit’s summary. Fixing bugs, improving algorithms, all of that can be intuited from the code. What can’t be intuited is why that code exists. What inspired the creation of that code? What inspired this typo fix? What should I check to ensure this commit does what it should do? What problem might I see again if I revert this commit?

      That context, being with every commit every time, helps. Even when I write quick commit messages, just two lines, under 50 chars, I can look back and still get something useful from that message.

    2. 23

      Personally, I prefer the imperative for the subject line, and no period at the end. For some context:

      1. 8

        Ditto. I usually directly pass this around as it is actually quite recapitulatory: https://chris.beams.io/posts/git-commit/#seven-rules

      2. 12

        I’d be really hesitant to link a Slack thread in a commit message. Even permissions aside, Slack limits the history access on some plans so this link may soon become invalid.

        1. 4

          I prefer analysis and notes go in a bug tracker for a variety of reasons (e.g., you can amend it later if URLs change or to make it clear the analysis was somehow incorrect) – but, yes, whether in bug notes or in the commit message itself, it definitely feels better to paraphrase, summarise, or even just copy and paste the salient details rather than just link to a discussion in some other potentially ephemeral mechanism or something volatile like a gist.

          1. 1

            Agreed, IMHO details and discussion should all be in the bug tracker - not in Slack or in commit messages. The commit message should have a short ”what does this change do” explanation and a reference to the bug tracker where more details can be found if needed. I don’t agree with the need to put an entire essay in the commit message that seems to be popular on the Internet.

            1. 16

              My 12-year-old codebase is on it’s fourth bug tracker. None of the links in commit messages still work, but the repository kept history when it got converted to git, so 12-year-old commit messages still carry useful context.

              1. 2

                As other comments mention, commit history has a longer lifetime than bug trackers. Of course, you can port your tickets when you change trackers, but will you?

                1. 2

                  Yes, of course. Not migrating your hard earned knowledge would be an incredible destruction of time and money, especially in a commercial setting.

                  1. 1

                    Commits are for non commercial settings as well, and sometimes migration can’t be done e.g. when you rehome but don’t move a GitHub repository (if for example original access controls were vested in single humans who then apparently vanished).

                    Keeping content in an issue tracker is nice, but it’s always worth duplicating knowledge into the git commit.

                    Catastrophic data loss can always happen, even in commercial settings.

              2. 1

                I mostly agree here. But I do think that links can belong in a commit message, like when referencing a design document. Since design docs are usually a snapshot of a design of a feature, that usually has context on motivations for some of the decisions that are too long to type out in a commit message, as well as discussions.

              3. 1

                Interesting point. It’s a trade-off between providing context easily and future proofing. I was assuming a paid plan, which has no historical limits. I don’t think free slack is a good fit for this, because of the memory hole.

                1. 2

                  I’m fine with linking to a fully fledged bugtracker we know we’ll keep using (yeah…) but something like Slack feels far to flimsy to me. It’s not clear where the context begins and where it ends as the discussion often evolves and drifts away to other related topics. A chat platform just isn’t a fit here in my opinion.

              4. 8

                I am compelled to drop in Stephen Ball’s Deliberate Git video every time commit messages come up. It’s been 7 years since he presented that talk at Steel City Ruby 2013 and I still show that video to interns, early career folks, and new team members of every vintage at least once per year if not more often.

                1. 4

                  I actually work with Stephen now, and the quality of our git commits has gone up tremendously!

                  1. 2

                    Yeah, that’s what I immediately thought of. It’s a great video and I probably need to rewatch it.

                    1. 1

                      Thanks, I’ll give it a watch.

                    2. 8

                      I am not sure I agree with a blanket „write good commit messages“ advice, which doesn’t precisely delineate the context when it is and is not applicable.

                      Empirically, for the code I’ve been writing during the past few years, good commit messages never really helped me. As a result, i rarely go past the summary line (representative sample of commits). The reason for that is that a rarely use fit history, and when I do, the changes are usually self explanatory.

                      What I do find useful for me is doing really tiny commits, and constantly cleaning up small things. And spending time thinking about commit messages in this context is somewhat counter productive.

                      1. 1

                        This is a good point; like any blanket advice it won’t apply in every situation. I have found it useful when on teams or when I revisit older code because I have been switching between projects. It’s really about communication, either in team or across time. But, as they say, ymmv.

                      2. 6

                        It’s quite annoying when you work with someone who doesn’t properly document their work but it’s especially frustrating when that muppet is past-you. Be nice to future-you, he’ll buy you a beer later!

                        1. 2

                          Past-you is the worst!

                        2. 5

                          This is quite similar to the approach I take, so it’s good to see others doing similar. I also use the git add -p approach to force myself to review each change so I can make note of the “why” in the commit message - or perhaps omit a hunk to put into a separate commit.

                          I tend to write commit messages for “future me”. Sure I’ll remember the context of the change for the next few days, perhaps a week or a month, but after that I’m guaranteed to have fogotten exactly why I did a thing, so I try and document the “why”. It’s not uncommon for me to write a commit message that’s two or three paragraphs for a one-line change.

                          1. 2

                            One thing that has really helped my company improve its commit messages is having a template for pull requests that includes section headers. People can remove the headers if they’re irrelevant but it then becomes a conscious decision to skip those sections, rather than requiring a conscious decision to include them.

                            Brief plug for Phabricator here – its support for commit message templates is much better than GitHub’s.

                            The specific section headers in our template are “Asana Link” (replace with Jira or whatever), “Description,” and “Test Plan.” That last one has some additional conventions: it should describe what someone else needs to do to test your change locally. Not because we necessarily test each other’s PRs regularly, though we sometimes do, but more because framing it that way has proven to be a good forcing function for getting people to think through how they’re testing their changes. If a change is fully covered by automated tests, of course, it’s fine for this to just be, “Run the test suite.”

                            A strict 50-character limit on the title, though, is where we part ways with the typical advice about commit messages. We use a monorepo and have a convention of putting the component name in the commit title as a prefix. It is super useful when we’re running git shortlog. 50 characters minus the length of the component name is just too little space to write meaningful titles.