1. 20

  2. 13

    I try to write meaty commit messages. Working in FLOSS projects where the original author is long gone have taught me they are invaluable. But all the posts about writing good commit messages are missing the point. The main reason why people don’t make the effort to write a good commit message is because they don’t read them in the first place. If someone sees commits as a write-only medium why are they going to make an effort when writing them?

    Ask around, how do other people navigate the history of a file/function? Many of them will tell you they use GH’s web interface to navigate the history of a file, and that is awful way to do. The first step should be to teach them people how to use a tool similar to Emacs’ vc-annotate

    You should use the imperative mood when writing commit messages.

    I would add an additional reason, because git use imperative mood as well. ej. ‘merge pull requests’.

    Btw /u/lazau, there is a typo in the line above, (imperitive).

    1. 3

      Thanks for the feedback. For context I work in a large codebase where the original author is usually also long gone :). I agree that most people see commits as a write-only medium. I think I could add more motivating examples so that people can see why good commit messages might be valuable.

    2. 3

      As outlined in the article, I wrote this in order to help some interns close a skill gap I saw in their internship. I plan to write a couple more so that I can help interns hit the ground running in their software development careers. This is the first time I wrote anything like this, so please let me know if there is any room for improvement. Feedback is more than welcome!

      1. 3

        Considering that the short summary is generally limited to 50 characters, should punctuation be used there? I’ve seen mixed opinions on this and have been called out on putting a period at the end of my commit messages.

        1. 3

          With the caveat that you should follow the style of the repo you’re working on, I prefer to leave out the period at the end. If you ever use the e-mail based workflow, the first line is used as the subject, which you usually do not end with a period. Also git does not do it in the messages it generates for merges and such.

          1. 1

            Aha! So that’s why it’s also called the subject line.

            That’s a great analogy for what that line is for – too many people treat it as a paragraph.

        2. 2

          There are things not to put in a commit message too. Commits are history, and get buried over time.

          Any info that the reader needs to know in order to safely interpret and modify a piece of code probably belongs in the code as a comment.

          1. 1

            At my work place we use a convention similar to the angular one.

            As starting element we use the task number, as we treat tasks as part of the documentation.

            In there we got design resources, links to additional docs and stakeholders comments.

            Using comments that way, the git log --oneline turns to be like an index for your documentation.