How to Create Good Git Commits

September 24, 2018

A commit captures a project's snapshot. It stores the changes that you've made to your repository since your last commit. You stage the changes you want to store and then by committing, you incorporate those changes into your repository where they become part of the most recent revision. This cycle of modifying your project, staging your changes, and committing them forms the core of your version control work.

What makes a good commit? Good commits are small and focused. They cover just one task in your development work. A bad commit may contain, I don't know, three bug fixes and four new features and some refactoring. And that's just too much work. Say you need to roll back just one of those bug fixes or you have to remove one of those features. Unless you saved a single major change in each commit, you won't be able to do that. So, limit each commit to one step forward in your project development. You know you've done too much at once when your commit message sounds something like "added several new features" or "updated a bunch of things." You should be looking for messages that sound more like "fixed bug that cause screen to flash while scrolling" or "added secure password storage." These are excellent commits. They focus on a single task.

Focused commits simplify your git history. You understand what changed at each commit when look through your log output. Good commits make it easy to revert a single change when needed. If you added several new features, well, good luck splitting out just that feature that's causing your one-star App Store review or worse, your one-star performance review.

Good commits use good commit messages. A commit description should fit on a single line and it shouldn't take up so much space that you can't read it with a single glance through your git history log. Your message should be declarative. And there's a bit of a holy war about the exact message grammar. So, make sure to follow whatever practices are most common for your place of work. But the prevailing industry standard is to write messages as if they started with "This commit will." For example, this commit will make DWARF debug flag behavior match Clang, or this commit will explicitly check for 'inout' parameters on objective C-functions. Using git commit -m is a great way to track your changes and leave descriptive commit messages. Now that you've learned to create a succinct and informative commit messages, use git commit minus M plus the message to annotate your commits.