Archive for February, 2011

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.

Comments (2)

MacHg 0.9.14 released!

I just released MacHg 0.9.14 which adds the ability to drag and drop from the browser to the dock or finder; improves importing and exporting patches; fixes a major bug to do with very heavy processor load and visual flickering; updates the Mercurial bundle to 1.7.5; handles the new security model of Mercurial 1.7.5; includes TrustedCertificates for https connections; fixes handling of external diff tools for the users who were having issues; and fixes or addresses many smaller issues including: #136, #148, #158, #159, #163, #164, #173, #178, #179, #181, #185, #189, #192.

It feels good to get this version out the door since it fixed that very infrequent but fairly serious bug of maxing out the processor and causing page flicker. It was really hard for me to solve this bug since I couldn’t reproducible it. But finally in the end through users help, I found an example which could reproduce the problem. And happily with that I solved the issue.

I will also comment and say that the new security changes in Mercurial 1.7.3 & 1.7.4 are for the better but adding the corresponding support in MacHg was not without some pain. Most of the changes which occur to Mercurial these days are pretty much internal changes but the security changes in handling https were definitely changes that had to be accommodated by GUI writers like me.

It was also good to nail that complaint which I also couldn’t reproduce about external diff tools not working correctly, since they worked fine for me… (It turned out that the users didn’t have /usr/local/bin on their path, whereas I did through /Users/jason/.MacOSX/environment.plist)

Anyway, with those changes, things are coming along really nicely. MacHg 1.0 is nearly here…! 🙂

Comments (3)

Thanks Joe!

I want to thank Joe Workman who is a user of MacHg. He designs lots of stacks for RapidWeaver + Stacks. I use Rapidweaver for doing the MacHg website and it’s pretty efficient. I had always been meaning to play with some of the javascript tools to do fancy things, jQuery, etc. However, Joe was really nice and donated all his various stacks to the MacHg cause and so now I am using a few of them in the site. And… well… I didn’t have to learn jQuery (at least not yet…) That rotating log of mini-screen shots on the front page now is done using Joe’s stack Gyro! Its very nice to have something like his stacks which are just smooth and easy to use. So, Joe, thanks!

Leave a Comment

Unified diffs and GUI clients

Recently a user of MacHg asked how to display the differences in a file inside MacHg.

I personally have an opinion on this which differs somewhat from the established dogma. Thus I will outline my position here so I don’t have to elaborate it elsewhere, and hopefully it will make other GUI designers at least think about this issue.

The situation right now is that almost all GUI clients for Revision Control Systems (RCS’s) show differences “in application” through unified diffs. This is done because unified diffs are rather short and compact. But unified diffs don’t show all the surrounding code; and really in a large section of code with several changes, it is very difficult to immediately see what changes are occurring.

In fact, every single external GUI diffing program that I have seen has as default a side-by-side diff. (Some programs allow as an option, unified diffs, but it’s definitely something which is not the main thrust of the program.)

So, why does every single program that is dedicated to showing differences, display differences in a way different to that used inside almost all RCS GUI clients?

The reason is that most people sooner or later are forced into being able to recognize unified diffs. And after much exposure they begin to expect to see unified diffs, even though they are a very suboptimal way to view diffs.

Why do people get used to unified diffs? The reason is that since unified diffs are the raw format for diffs and are plain ASCII, they can be easily emailed around and inspected by people using tools which have nothing to do with diffing (eg email clients, text editors, displaying text on a web page, etc). In fact in some lists, sending unified diffs is the default way to exchange information, since in email ASCII is the lowest common denominator. (For instance, the mercurial development mailing list uses unified diffs as an interchange means of publicly discussing proposed changes.)

Of course, email is a very convenient interchange system, so developers are reading these unified diffs all day. Thus when some developer goes to create an RCS GUI client, they naturally put in the stuff they are working with all day, eg unified diffs.

But let’s take a look at what happens here in a screen shot from another RCS GUI client. (Note: I am not singling out this client amongst others, since many other clients do exactly the same thing.) However, of the overall window size (892 pixels x 689 pixels) the part which shows this unified diff is quite small (624 pixels x 192 pixels). Thus, just 19.5% of the window size is dedicated to showing the differences from one version of a file to the next in a semi-obfiscated patch interchange format.

I think its just sub-optimal.

(Of course for some die hard developers who eat, sleep, and breath unified diffs, maybe having some in program unified diff display is semi-convenient. However, to a large degree such people tend to use the command line in any case, so dedicating GUI features for them is futile.)

In this day and age of 32 inch LCD monitors, I think GUI RCS client programs need to live a little and somehow encourage the showing of diffs in the format that well… all dedicated GUI diffing programs use. Ie right now, use a very fast dedicated client or in-application code which shows the diff in a side-by-side format with full context in a large window.

(That said I have had more than a few requests for this feature in MacHg. And I try and do what users want… So maybe later I will have to toe the line and add these unified diffs into MacHG… But I am resisting for now…)

Comments (1)