The Good: Commit

You may have encountered statements like

Commit early, Commit often

We agree. Apart from acting as checkpoints, good commits support collaboration by providing an overview of your changes and make navigating them easy. But only as long the commits are good.

The good commit follows Git best practices

You are encouraged to follow commonly adopted Git best practices. We would especially like to highlight:

1. Try to make each commit a logically separate changeset
   • Make changes in each commit atomic – focus on one thing
   • Keep your commits as small as possible and keep your changes in each commit related
   • Utilize git add --patch if you need to split non-related changes into separate commits.
2. Commit often
   • It is easier to get an overview with multiple small changes than one large commit containing lots of changes
   • If you need to roll back to a previous commit, you can do it incrementally instead of reverting every change
3. Strive for each commit to compile/build and pass tests
4. Regularly push your commits to remote
   • Early peer reviews are easier
   • In case something happens to your machine it reduces the amount of work lost
   • Makes it easier to hand over the issue to other developers if needed

The good commit has good commit messages

Keep in mind: This · has · all · been · said · before

— Chris Beams, The seven rules of a great Git commit message

All commits from your branch are squashed when merged with the main branch (see commits). Commit messages from individual commits end up in a list of changes in the message body of the merge commit. Try to keep that in mind when writing your commit messages.

Ideally, a good commit message will be structured into three parts:

1. Subject line
2. Message body
3. Closing line

The most important part is the subject line. The message body should be used if elaboration is necessary. We rarely use a closing line, but if you want to add useful meta-data related to your commit – such as GitHub issue number and co-author names – this is where to put it.

A good subject line

• will complete the sentence "If applied, this commit will..."
• is written in imperative mood (Fix, not Fixed, Fixes etc.)
• is limited to 50 characters

If you cannot fit your message into a 50 character subject line, consider if you've included too many changes that makes it difficult to describe concisely. Try to rephrase the subject line and use the message body for elaboration.

In addition we use gitmoji when possible to prefix the subject line with an illustrative emoji. There are several tools available (including a VSCode extension and a CLI tool). It's optional, but very helpful when skimming through the git log.

Good verbs to use as the first word of your subject line:

• Add
• Create
• Refactor
• Fix
• Release
• Document
• Modify
• Update
• Remove
• Delete

🟢 Good subject line examples:

📝 Update getting started documentation

🔥 Remove deprecated methods

✅ Add tests for dropdown component

🔴 Bad subject line examples:

fixes a bug.

more changes

added file

fix code review comments

A good message body

We don't often use message bodies, but we encourage you to do so if you need to elaborate on your changes. Here is some pointers on how to write a good one:

• Always separate the message body from the subject line with a blank line.
• You should use the message body to describe what was done and why, but not how (see for example this commit from Bitcoin Core).
• Be aware that if you need to write a lot in the message body it may also be a sign of too many changes in one commit.
• Wrap lines in the message body at 72 characters

Read more about good commits

For more on good git commits, see (among many other):

• Distributed Git - Contributing to a Project
• Git Best Practices
• Stop Writing Bad Commit Messages
• How to Write a Git Commit Message
• Turbo Git Commit Message Standard
• Check Out These 5 Git Tips Before Your Next Commit