I use git and github.com for almost all of my work including research manuscripts, teaching content, and my website.

When you use git (or any other version control software) and you make changes to files, you need to record those changes in a commit message. These commit messages provide a brief summary of what changes have occurred in the history of the files and can allow you to back in time to a previous version of the file. But the messages are only as useful if they are written well and therefore it is important to have a process to write those commits.

I found a post by Chris Beams that provides suggestions about how to write commit messages. The most important is that a commit message should finish the sentence

If this commit is accepted, it will…

His post also has seven rules for writing commit messages. I’m repeating them here, but you should check out his post for more details about each of these rules:

  1. Separate subject from body with a blank line
  2. Limit the subject line to 50 characters
  3. Capitalize the subject line
  4. Do not end the subject line with a period
  5. Use the imperative mood in the subject line
  6. Wrap the body at 72 characters
  7. Use the body to explain what and why rather than how

So the caveat to finishing the above sentence is that the message should be capitalized and should not end in a period.

I work with enough researchers that use git and have no process for writing their commit messages that I’m hoping this will provide some guidance.

blog comments powered by Disqus


21 October 2021