History Editing in Mercurial is Standard Practice.

It’s a standardly espoused mantra by some people using DVCS’s that history editing is bad / evil. I don’t agree.

In fact MacHg has sheet interfaces to strip, histedit, rebase, collapse, and amend commits. I use these features constantly. With a little care and safety most intermediate Mercurial users should be using these history editing features too… Or at least know what history editing is and what is possible. If you standardly do a clone before editing history, there is zero danger of loosing anything since to undo you simply revert to the clone.

Personally, I tend to work on my code for a while adding, polishing, moving bits around and then push stuff in a clump. I do a lot of “history editing” before I push. My typical workflow, and I would assume that of others, involves a lot of development time consisting of small little tweaks. I often commit before I compile just in case I mess something up. Then I start testing the new code. I will often then find some simple typos, or maybe missed including something. Then I simply do an amend commit. Once I have things compiling, the next changes either go in their own commits if they are big, or are amended into the previous commit if they involve simple small oversights.

Even though amend is not a standard part of Mercurial, I added amend specially into MacHg since it’s very useful. It’s available in the advanced options of the commit sheet: The Amend Option

(I will often use histedit to move things around until they are in a nice order for later historical understanding so that when I or someone else looks back 6 months from now I / they have some hope of following what I was doing. In fact I often don’t worry too much about the commit message. I often go back once things are moved around and organized into shape and change the commit messages to something detailed and sensible… Of course I do this on the stuff I haven’t yet pushed to the wider world. Note to do this editing I often make throw away clones just in case something goes wrong with the history editing process, so I can just step back to where I was. At some stage it would be really nice to have a wider undo, rather than the limited rollback we now have… But thats the topic for other emails…)

I commit early and very often. But many of my commits are not logical chunks or they go down blind alleys etc. Thus history editing is really really useful. In fact one of the largest examples of this close to home is the Mercurial python source code itself. The commit history for the Mercurial project itself is quite clean and the quality level of the patches before they are applied to the mercurial sources is quite high. There are very few: “Opps, include that header”, “Opps change the spelling here”, “Opps, make sure it compiles under linux”, “Opps, make sure it passes this test”, etc. sorts of commits in the Mercurial source tree. Thus in one way or another the ethos behind the Mercurial project’s revision history is a clean one.

Consequently it appears to me that its somewhat iniquitous to see that the Mercurial project itself keeps a very clean history where the patches sent in have obviously been history edited in one way or another, but tends to espouse the position that history editing is evil, and all you people just keep whatever intermediate erroneous commits in your repository because its good for you. (even though we don’t keep them in our history ourselves…)

In any case the clear shining example here is that the Mercurial sources themselves are clean from the “opps” sorts of commits. So somehow users would also like to have similarly clean and followable commit histories. You do this through amending, rebasing, collapsing, reordering, and rearranging your changesets.

When you are starting out with history editing, make sure you make a clone of your repository before you do the edits just in case you mess things up. Actually the most dangerous time for users in reference to history editing is probably not when you are starting out, but when you get comfortable but are still not yet really experienced, and things are going fine and you have done lots of edits before, and “Well I will just skip that step of making a clone, and I’ll do all the edits at once instead of in steps so its a bit quicker and, opps…” Also most people on OSX will have time machine running and backing up there repositories, so in case of a major stuff up you are at most going to loose an hours work. (Note this has never happened to me.)

I’ll try to do a screen cast about history editing at some stage soon.


  1. Histrionic Said,

    March 15, 2011 @ 1:50 pm

    So does MacHg have an option or built-in process to make (or suggest making) a clone before history editing?

  2. jason Said,

    March 15, 2011 @ 2:10 pm

    At present no… This is basically undo, and as Apple says “great software supports undo”… I really want to write the undo extension to Mercurial and all of this would then be sooo much easier. I have tried prodding the Mercurial team, but as yet to no avail. I have ideas about this and it wouldn’t be that hard I think. Since Mercurial needs to break hard links whenever it writes to any files there is a single choke point where I can intercept any writes to files and then hardlink the file right there and so effectively create a backup cache.

Leave a Comment