Clean Git History is Kinda Overrated

An important thing I learned early in my career was that best practices need not to be accepted at face value. There are so many nuances to Software development that a rule followed religiously can bite you in the back somewhere in the future. It’s not easy to realize this, though. Often, you read about an idea, you are sold to it (without considering its wider implications) and next thing you know you’re married to it.

Utility-first CSS is an example of this. Web developers are tied to the idea of ‘separation of concerns’ so much that a framework like Tailwind reeks of the worst possible way to organize CSS. But for someone like me, who has seen the struggle to modularize CSS, Tailwind immediately clicks.

I am always lookout for things we accept without reason and clean Git history is one of them. How do I define a clean Git history? It’s where each commit is a carefully separated, and each change is meticulously described, where you try to interactive rebase a lot making sure that each change has its proper place. Don’t get me wrong. Clean Git history is useful, and in many cases a necessity. In a big open-source project like PostgreSQL, where stability is the utmost concern, each change being as through as possible is very much needed.

Neither I am advocating that your commit should be a big change with a message “bug fixes.”

What I am bothered by is the the lengths developers sometimes go to make sure commits are ‘proper.’ I see them interactive rebasing, editing commits, and moving them one above the other. Or more wastefully, taking lines of code in one commit, undoing it in that, and adding them to another commit, often leading to conflicts. And next thing you know you have wasted thirty minutes fixing your rebase.

I have a rule of thumb for judge any practice: did the time it saved exceed the time it took? In my years of experience, the answer here is absolutely not. While I do look at Git history now and then, it was never a big factor is trying to diagnose an issue or understand something. What has mattered more is the current state of the code. If the code is clean and properly commented (where is needs to be), I rarely needed to go through the Git history. I don’t have a reason to believe that the time I spent in abiding by strict rules, solving Git-related problems because of that, was anything more than wasteful.

Granted this might be truer for rapidly moving software teams than, perhaps, Google or Amazon. But having worked with a Software team of 75+ people, I don’t have a reason to believe that a crisis would brew unless the team size is exponentially more (500+ or more). Even then, few rules around commits is more than enough.

To reiterate, I am not disregarding everything related to committing changes, but only saying that - don’t go overboard. Things like,

  1. If you created a big change that’s too hard to break into individual changes, it’s not a big deal if you create a single commit and describe all the changes in the commit description.
  2. Don’t move lines of code between commits. (If you’ve a tool that makes it radically simple, maybe you can).
  3. It’s okay if you create a separate commit for code review changes. Interactive rebase to change the particular commit.
  4. Interactive rebase is although powerful can really get messy if you’re doing too many changes. Avoid if it gets getting really complicated.

I think it’s the engineering teams and managers need to loosen up first. In most cases, they have been oversold on the benefits of pitch-perfect practices, and undersold on a more rapid pace, moving by loose guidelines than a strict rules.

Subscribe

Enjoyed this post? Get an email notification when I publish.

comments powered by Disqus