Committing Using git is Easy, Right?

Well, yes and no. It depends on who is working on the project. If you are coding alone, everything is fine and you can close this post and live happily ever after. However, if you work on a software project with more than 0 other people, read on.

Everybody knows that guy that builds a cool feature with many, many lines changed and new files created and then, he gives it to you for a code review. But the problem is, that all the stuff he changed is in one.single.commit!

It usually looks like this:

This is the moment when you should stop the review, go to the Donald Trollface (the author) and kindly ask him (“yo bro, what the heck is this?”) to break code down to the series of small commits, otherwise you will not review it. Some folks are afraid to stand up and say: “I am not doing it”, and they proceed with the review of the monster-commit. In the end, they have just a few (or no) suggestions for the reviewed code - and it is not their fault. That’s because single-commit merge requests of this size simply cannot be reviewed reliably.

When you break down your code into small commits, you usually get many more comments than for a big single-commit merge request.

Is this a bad thing, that I get many comments for my code when the merge request is broken down into many separate commits? I think it’s the other way around: It is a good thing. Let me explain.

More Comments from Reviewers Usually Mean a More Thorough Code Review

In my experience, the more comments I get, the better the code review. Why is that? When the whole merge request is broken down into smaller, independent pieces, the reviewer can usually spot more errors and offer code improvements thanks to a laser focus on that single particular commit.

When you have a single huge commit, reviewers usually cannot focus on the details.

More Commits Unlock the Partial Review Feature

When you are the reviewer and the code you are checking is separated into many independent commits, you can easily start with the review just before the lunch or at the end of your work day, stop when needed and continue after lunch or the next day exactly where you left off before. When everything is in a single commit, you can’t. It’s either all-in, or you need to restart the review process completely after the break (at least in my case).

More Commits Reveals the Author’s Thinking Process

I personally try to make my commits in a way that mirrors my thinking about the problem being solved. The first commits are usually some sort of setup and preparations for the main thing, that comes in later commits.

For example, when you are storing logs on the disk but you also need to implement writing them into database, the first commits would be about setting up environment variables, the next commits would be about creating database connection and the last commits would be the feature itself - writing into the database + tests.

A single image usually speaks more than a thousand words, so this is how it usually looks in my case (the commits are sorted by time from the bottom to the top, so the first commit is Add shopping-cart-service environment variable to example):

Making Small Commits?

I hear you:

How can I break the code into small commits right from the beginning if I do not know what the final code will look like?

That is a valid question. I don’t know what my code will look like right from the beginning either. I have two approaches depending on the size or difficulty of the feature being developed:

  1. Implement the feature completely without committing anything. After I am satisfied with the code, I proceed with creating the commits in a manner that I would love to see if I was reviewing someone else’s code: logically sorted, subsequent commits leading to the result. For people working in command-line git, learn and use git commit --patch. I haven’t been able to live without it since a co-worker taught me how to use it (thanks Michal).

  2. I occasionally commit during the process of writing code when the change is isolated enough, or when I am sure I will not change this code in subsequent commits. Even If I am wrong, and I need to change already committed code later, I use the git rebase’s features (namely squashing and rewording commits) to fix it. For people working in command-line git, I strongly suggest you to learn git rebase too. Again, once a co-worker of mine taught me how to use it (thanks Michal), I cannot live without it.

And just a reminder: Always try to be as descriptive in your commit messages as possible. Messages like “code” and “more code” really say nothing at all. See this very informative joke taken from xkcd

What Comes After Code Review? Squash Time!

Because you made lots of small commits, your colleagues can review it comfortably. They loved you very much and did a great review job. You happily resolved all their comments. So now what? Making small commits is great for purpose of the code review, buy you do not want to add 40 commits into your git repository’s history after merging.

I mentioned the git rebase’s command squash ability earlier. I use it for squashing, rewording, and rearranging the order of commits. When my merge request is approved, I squash the multitude of smaller commits into bigger ones, so they make a nice and easy-to-read history in git log.

I sometimes squash into multiple commits and sometimes I squash all into single final commit. It always depends on the situation and I do not have any universal rule for that, just a gut feeling.

In the example from the image above I squashed everything into a single commit:

Conclusion

To wrap up: Commit often, make those commits small and isolated, and write self-explanatory commit messages. It might seem like a tedious job at first, but I urge you to try this approach. You invest a lot of time into crafting your code to be top-notch, but you should also invest a fraction of that time to make your reviewer’s life easier. They will then spot more potential problems and suggest improvements to make your code even more exceptional! And that is hard to be done when reviewing one huge single-commit code. Start with small commits today! Your colleagues will love you for it!