1. 11
  1.  

  2. 9

    One thing I always want to tell people about commit messages:

    There’s no length limit.

    In fact, write as much as you can. Go crazy. Write some more. Explain. Talk about how your day went. Tell us how you found the problem. Put benchmarks that show why your change makes things faster. Show the stack trace or test output that you’re fixing. Quote other people. Put an email chain in the commit message.

    In a well-curated commit history, commit messages become source-level documentation available via an annotate/blame operation. Most people hate writing documentation, but commit messages are about the only time when our tools force us to write something. Take this opportunity to really write something. It’s the only time when writing is really required in any way. There’s no need for a length limit because most of the time the commit messages are hidden away, and most interfaces will hide the full commit message anyway (or can easily be configured to do so).

    If you want practice jamming lots of information into a small amount of space, that’s what the first line of the commit message is, but after that, don’t feel constrained by length limits.

    These are examples of my favourite kind of commits:

    https://www.mercurial-scm.org/repo/hg/rev/4fb2bb61597c?style=gitweb

    https://www.mercurial-scm.org/repo/hg/rev/ed5b25874d99

    https://www.mercurial-scm.org/repo/hg/rev/1423ff45c322

    https://www.mercurial-scm.org/repo/hg/rev/dd028bca9221

    https://www.mercurial-scm.org/repo/hg/rev/8d5584d8345b

    1. 1

      I agree in that length limit hinders rich information being put into the commit to better explain the intent and reasons of the changes. However, GitHub/GitLab hasn’t really make it easy to read long commit messages in their UI, which is a bummer.

    2. 3

      Deliberate Git by Stephen Ball remains my favorite talk on the subject.

      1. 3

        Just for kicks I’ll post a comment that this is cargo culting. I see no reasoning in the post justifying why this commit message format is good or even better than some other format. I think this article is 90% “Linus wrote up how he likes commit messages one time and I’ll just repost that”.

        The subject should start with a capital letter and should not end with dot.

        Um, why? How is this better than “The subject should be a single lower-kebab-case token and end with an ellipsis”?

        I personally don’t think leading uppercase or trailing dot matter a single iota. Who cares and why?

        A properly formed Git commit subject line should always be able to complete the following sentence

        Um no. If anything, this rule implies that the commit subject should start with a lowercase letter, not uppercase.

        In my experience, the whole subject/verb/object thing is a triviality a lot of the time. If I add a file “about.html” and my commit message is “about page”, if I make it “Add about page” how is this meaningfully better?

        less than 50 character

        So if I want to be precise and say “Update to latest some-library-with-long-but-important-name” do I truncate it? Who cares?

        Sometimes commit messages are of moderate importance and utility. Most of the time, I get the info I need from the diff. If it’s really important, put it in the source code as a comment.

        1. 1

          I constantly break the commit title rule.

          One useful aspect in perusing the commit log by headings only is to have [foo] [bar] type of tags in the beginning. One atomic commit can touch multiple files in multiple systems, even if it’s not a messy megacommit, and I like that.

          Anyone else into this?

          1. 1

            I think this is perhaps more a criticism of people’s tendency to follow a set of guidelines dogmatically. I agree with you, and I like the critical-thinking devil’s advocate approach you’re taking. There’s certainly value though in a developer being aware of expected style than no awareness and the resulting free-for-all.

            1. 1

              A long and important library name has a short and relevant description. Commits are written to be read, and the tools need a short first line so everybody can always read them.

              Expressing complete thoughts in commit messages mean nobody has to go read the committed code to know you definitely just added the about page in that commit, and didn’t maybe import it from somewhere else.

              1. 1

                the tools need a short first line so everybody can always read them.

                So the repo has hundreds of files where the tools can read 80-character lines, but for some reason the git tools need 50-characters for the commit message? I don’t get it. One particular git command line tool wants space to put the commit hash to the left of the commit message, and we just accept that as essential? I don’t need to see commit hashes in my normal workflow. Is word wrapping a reasonable solution we should expect from our tools? I think it is.

                nobody has to go read the committed code to know you definitely just added the about page in that commit, and didn’t maybe import it from somewhere else.

                I agree if I grabbed an about page from somewhere else, mentioning that in the commit message after the subject line would be helpful and a good idea, but I think a comment in the file saying “this file was copied from the old web site repo” is a better place to store that information if it’s really important, which it just usually isn’t. If I put in in the commit message only, what does that really mean? Does it mean nobody has to go read the committed code? I don’t think it does. Do I know that everyone who edits that file will read every commit message relating to that file all the way back to its origin? No, I do not. Do I know everyone who edits that file will read all the code comments either? Nope, I don’t even know that. In fact, the majority of commit messages and code comments alike will never be read by anyone in many projects, but the odds of being read are way higher for a code comment just due to the fact that it is shown alongside the code with the same tool used to edit the code.

                1. 1

                  Git tools expect certain line widths, that’s just how it is. Is it good that summary text can’t even be longer than 60 chars? It’s a standard, and you have to pick a limit somewhere.

                  Expressing a complete thought in a commit means you know for certain (probably, unless a problem is less likely elsewhere) what that commit does with relation to the repo. That’s the important bit too, tracking where you have original work, where something is vendored, and what’s going through your mind meta to the code. Git should track things that are important to the repo, and help people navigate the repo history in clear ways.

            2. 2

              I do.

              In all the time I’ve been using git (I was an earlyish adopter, mercurial user prior), however, I consistently get teammates approach me to ask about code before looking at git blame. Most people review PRs by looking at the entire diff too.

              So lately I ask myself if it’s worth the effort.

              1. 2

                I’m in the same boat at my current job. I have a small team of junior devs, and the practices they’ve learned from bootcamps and stuff, particularly in git, can be a be demotivating.

                I generally now just look at diffs. But, I do appreciate articles like these, and I definitely try to reinforce better habits.

                1. 1

                  Most people review PRs by looking at the entire diff too.

                  Are you suggesting not looking at the entire diff? Or just not only the diff?

                  1. 6

                    I review each commit in sequence.

                    Assuming the commits are written well, this is much faster as I’m reviewing related changes together.

                    When people put unrelated changes into the same commit, or related changes into different commits, I have to change mental contexts whilst reviewing, which takes away energy/effort from doing a good job of the review.

                    1. 2

                      I meant any care given to having the commits reflect my intentions is lost. It’s as if I’d pre-squashed all the commits.

                      1. 1

                        There’s still later, when you need to revert part of the work, and it’s easy because it was a single commit…

                        1. 1

                          That’s a big limitation of git. It should be much easier to back out a whole series of commits.

                          The typical git way to do this is to merge with ancestor so you can just back out the merge commit itself. Still not quite the same thing as undoing a merge, but close enough.

                          1. 3

                            I actually meant the other way around - I’ve made 10 sensible, self-contained commits and only have to revert one to fix an issue.

                            That means that I get to keep the rest of the functionality I built running while I rollback one change.

                            If your change history is a spatter of half-commits and unrelated changes are rolled together, you have to manually pick apart the bits you want to rollback (or just reset to a known good state).

                            Even if a reviewer isn’t using the commit log, the operations team and future maintainers are.

                  2. 2

                    One of the most memorable technical posts I’ve ever read is this one on how to write a good commit message. It wasn’t something I had ever thought of before, but in hindsight, it’s such an underrated skill.

                    1. 1

                      IMO this is too formal and dogmatic for commit messages.

                      Good commit messages should reference any cases/issues they’re addressing, give a brief description of the change, and mention any “gotchas” like “WIP” or “doesn’t pass unit tests”. Anything beyond that should be documented somewhere else.

                      1. 1

                        Pet peeve. Commit messages that lock you in to a git platform. What happens if you migrate to self hosted git? What happens if your repo goes away and now your issue counter starts from 0 again?