Mercurial: CVS to HG Recipes

Checkout a specific revision/branch

First, do a clone of the repository (as HG always maintains a local copy of the repository), then do an update to get your working directory on the appropriate branch.

  • MercurialEclipse: File…New…Project…
  • Choose Clone repository using Mercurial
  • enter URL for repository want to clone. Generally, would be central repository
  • enter username and password if required
  • by default, the parent directory will be the workspace. If you wish to override, enter a value for Parent directory
  • by default, the name of the directory that contains the repository (and subsequently, your working copy) will have the same name as the last directory of the clone. For our purposes, we’ll generally call this rdis
  • Select Search for .project files in clone so all projects will be automatically added to your workspace
  • If you don’t want the default branch, select Do not update the new working directory
  • If cloning over a LAN, Using uncompressed transfer is supposed to be faster
  • If you know the name of the branch/changeset you want to use, enter it. Unfortunately it’s a text field, so easier to not update working directory, and do a second step to get branch you’re interested in.
  • Wait for the clone
  • Once the clone is complete, right-click on one of the projects (this is a BIG difference from dealing with CVS.), and select Switch To…
  • From the dialog, choose the Revision or branch you want to work with. Normally, we’ll be dealing with Branches.
  • Your working directory will now be at the tip of the Branch selected.

See outstanding changes

  • MercurialEclipse updates the icons in the Project Explorer and Navigator, and also has a synchronize view. They even added an expand all to the synch view.
  • If you’ve synchronized before, can merely open synchronize perspective/view, and click the synchronize icon. If you want to change the options, select synchronize… from the dropdown options.
  • I would suggest synchronizing against your local repository, as otherwise, you’ll see changes in local as well as remote, which is confusing. I’m still investigating this to see if the synch view can be modified to use something more like hg status command, which should be very fast.

Add/delete/rename/move files

  • MercurialEclipse should take care of add/delete/move/rename operations. If it doesn’t automatically record an add/delete, then the commit dialog provides options for correcting this.
  • If a move/rename is not reflected correctly, may have to resort to TortoiseHG. Will have to see once start doing more intensive development

Get changes others have made to central repository

The important difference here is you have 2 locations. A copy of the repository, and your working directory. So, you can update your local repository without updating/impacting your working directory

If you have no local changes:

  • do a Team…Pull… and select Update after pull.
  • When press next, will show dialog with list of changesets. Finish, and local repository will have latest changes on ALL branches, and working directory will be updated to tip of branch currently on.

If you have local changes:

HG gives you more control over when, and how, your merge takes place.

Several options here.

  • Can do like CVS by doing a pull and update. Will show any conflicts in the implicit merge, fix up issues, complete changes, and then do commit/push accordingly.
  • Can complete your changes, do a local commit, then do a pull and update. If the merge from other’s changes causes any local changes, another commit will be required to correct these issues. At this point, can either do a rollback, or just commit 2 changesets. The commit, merge and commit approach allows you to do the merge with other’s changes, but you can easily get back to the point you were at when your changes were finished. This is helpful if someone else’s changes cause a lot of conflicts, and you need to try a couple times to get it right.

Commit changes so others see them

HG manages everything locally. You can do many changes/fixes without ever impacting the central repository, and still have full version control. A commit in HG terms is merely creating a changeset in your local repository.

When it’s time to share those changes, it’s called a push. MercurialEclipse adds an option to Team menu.

  • Right-click one project and select Team…Push…
  • The next dialog shows a list of changes outgoing. If it looks right, press Finish.

If you get an error about creating remote heads, and requiring a force, odds are you haven’t done a pull recently, and someone else has put a changeset in later than yours.

If so, you’ll need to do a pull, update, and possibly another commit before you do your push.


  • very similar process for viewing as in CVS. Shows in History View, but with graphical representation for branches.
  • Because of conversion from CVS, some changes are in the wrong order, so look at the dates closely
  • Also noticed an issue that some changesets from the conversion aren’t appearing correctly. Appears a changeset with a removed file isn’t appearing in the list. During simple testing, this doesn’t appear to be a Mercurial or plugin issue, but an artifact of the conversion.

Compare to other versions

  • Again, done same as CVS. The only thing to be aware of here is comparison is done against local copy, but also repository doing synch with. Hence recommendation of synching with local copy.


Tags in HG are very different from CVS. A tag is associated with a specific changeset, as opposed to having to be applied to each file, BUT they are version controlled. Also, there are local and shared tags.

So, you can create tags in your repository that will not be pushed to other repositories, and add tags that will be pushed to other repositories.

The ‘weird’ thing about HG’s implementation of tags is they’re version controlled in a file called .hgtags. So, in order to create an entry in .hgtags for a changeset, the changeset must already exist in the repository. A tag cannot be created at the same time the changeset it applies to is created.

This results in a commit for changes, and then a subsequent commit of the .hgtags file to create the tag. This also means that if you update to a tagged changeset, the tag will not exist yet.


Branches are lightweight, and can occur very often. For the most part, we’ll be dealing with named branches. These can be dangerous, so ensure you have a naming standard in place, or else names can clash.

When it’s time to branch, update working directory to the location you want to branch from. Then create a branch. Have to have outstanding changes before a commit will actually create the branch. Also, creating a branch is only local until a push is done.

Suggest having a branch.txt file that gets updated when a branch is created. Time to branch, developer creates branch, updates branch.txt, commits and pushes. Then other developers can pull and update their working directories.

If have changes, and want to update to another branch, MercurialEclipse seems to want to always replace any local changes. I believe TortoiseHG and HG allow for update/merge at the same time, rather than being forced to always lose local changes. Perhaps an option in MercurialEclipse I haven’t found yet?

Changes in local workspace, but need to do other work

In CVS, would take a patch, replace changes, make new changes, and then re-apply patch.

In HG, this can also be done, but there are also other options built-in to support this.

In MercurialEclipse, right-click one project, select Team … export patch…
Determine where you want to save your patch and the options to use.

Just remember that a patch doesn’t handle/track binary files.

Mercurial has 2 other options available. Shelve and the mqueue extension.

Shelve is a one patch storage area. Basically, it will create a patch, store the results and
revert your local workspace to the last changeset.

You can then make your changes, commit, push, and unshelve your old changes.

Just keep in mind that you only have 1 shelf to work with.

The mqueue extension is an advanced feature that also has many things to be aware of, so I won’t do more than mention it here.

It's only fair to share...
Share on Facebook
Tweet about this on Twitter
Share on LinkedIn

Leave a Reply