Use your commit history to tell a story

I always try and keep my commits focused on one thing. This was brought to my attention recently as I was doing a code review. A number of refactors mixed in with code changes.

Makes reviewing much harder to perform, and harder for both developer and reviewer to ensure things are correct.

Git has many features for helping with this. Find a refactor part way through a change, then pull out the refactor portion so it can go into its own commit, and continue with your code changes.

Doing a large refactor and want to make it smaller? Again, git supports that.

When coding, think about both your validation of the changes as well as a code reviewers view. As soon as there are more than 100 lines of code in a commit, and especially if there are a number of contexts, the review quality goes way down.

Git: Better commit messages

To push yourself to write better commit messages, consider defining a better starting template.

Place the following text into a .git-message.txt file in your home directory:

# If applied, this commit will...
# Explain why this change is being made
# Provide links to any relevant tickets, articles or other resources

Then do

git config commit.template $HOME/.git-message.txt

Now when you do a commit, the above comments will appear and remind you of the important parts of a commit message.

Obviously adjust it according to your project’s standards and requirements.