June 11, 2014 •

There are a lot of hard things when it comes to Computer Science: cache invalidation, naming things, off-by-one errors and, as it turns out, agreeing on the actual number of said hard things.

Good names capture the role and function of the concept being named, which, in turn, affects how you or others can understand and reason about stuff. Bad names complicate perception, muddy waters and can often lead one to incorrect conclusions.

One of the illustrations of the phenomenon of a “poorly chosen name” is the concept of “editing history” in the context of a distributed version control systems.

Why History?

In any nontrivial software project, code is read much more often than it’s written (that is, unless you’re writing in Java). Good code and good comments alike make it simpler to understand what the code does and how it does what it does. Version control systems complement actual code and make it simpler to understand why it was written.

Now, just as code, history can be good or bad. Bad history is easy to spot, and we’ve all seen it. Empty commit messages or messages similar to “i dunno, maybe this works” or “Oops, forgot the comma” or “!!!DO NOT CHECKOUT – DOES NOT COMPILE!!!”. Elephant-sized commits affecting dozens of files with no rhyme or reason.

Why Clean History?

History in a version control system should be about logical changes that lead to introduction of a new feature, bugfix, performance tweak. It should not be about “raw” and “unprocessed” changes. It should not be about editing physical bytes. Rather, it should be about why the code was written this particular way.

DVCSes allow us commit early and often, but with great power comes great responsibility. Nobody wants to see how you fix a typo in a variable name or backtrack after programming yourself into a corner. It’s a sign of a good software engineer to pretty up your commit history before unleashing it in public.

Why Edit History?

First of all, let me show what real history rewriting looks like:


Dictatorship aside, here are the reasons why I think “editing history” is a misnomer.

The first one is technical. “Editing” or “rewriting” means taking something and changing it in-place. Yet if you commit -–amend or rebase (either in "stock" Git or with Changeset Evolution enabled in Mercurial) you are not changing history. You create an “alternate” history, in which your commits unfold differently than they originally did. There’s nothing destructive about it, contrary to what the name “editing history” implies.

The second is social. Every so often you come across an article postulating that “Pushing rebases is evil!”, where authors tell their tales of grave horror about what happens when one exploits the superpowers of editing history. This mindset has its roots in limitations of tools; we just need to version control our version control.

What Instead?

I don’t expect to turn the world upside down with the revelation of mine, but I think I’m onto something here.

When you’re cleaning up history before letting the genie out of the bottle and pushing it upstream, you’re not “editing” or “rewriting” history.

You are deciding history.

comments powered by Disqus

HgLab is a behind-the-firewall self-hosted Mercurial server and source control management system which gives you:

  • Sophisticated Mercurial-based version control system
  • Straightforward setup on your servers
  • Powerful code collaboration platform
  • Seamless integration with your infrastructure - including ActiveDirectory

Get Started with Full-Featured 45-Day Evaluation →

Interested in HgLab and Mercurial? Want to know when new releases are out? Join the HgLab HQ Mailing List for to get notified when something interesting happens.

Subscribe to the HgLab HQ Newsletter →

Take HgLab for a Spin

Try HgLab now. Full-featured 45-day evaluation, no credit card required.