Using Mercurial on CodePlex

There’s ton of documentation out there on how to use Mercurial and its various clients. For this blog post, you’ll see me use a popular client called TortoiseHg. (Hg is the chemical element symbol for Mercury, hence Tortoise ”Hg” in case you’re wondering.) If you’re already familiar with TortoiseSVN, this will be very straight forward. 

Step 1:  Install TortoiseHg

You can install TortoiseHg from Note: TortoiseHg is an extension of the Windows Explorer shell, so there is no application to launch.

When prompted for your personal information, the username you specify will not be associated with your CodePlex account. This username is only used for your local commits. We advise you to put in the same username as your Codeplex username.

Step 2: Create a new CodePlex project

In the Create a Project wizard, select Mercurial for Source Control.

Step 3: Clone the repository

Now you’ll want to create a local clone of the repository. You must do this step; otherwise, you cannot push code (i.e. check-in) to CodePlex.

First, create a new folder on your local machine where you want to download (or clone) the repository.

Next, use TortoiseHg to clone the repository in the newly created folder, as shown in the illustration.

Clone command

You’ll be prompted by TortoiseHg for the Source path. You’ll need to get this URL from CodePlex. Go to the project, click on the Source Code tab, and under Source Control Setup, click Mercurial. You’ll see a window appear with the Clone URL.

Source Control Setup

This is the URL to insert into TortoiseHg Source path, as shown in the below.

TortoiseHg Source Path

Press Clone.

Once the clone is completed, the dialog will close and you’ll see a green checkmark indicating this is sync’ed with the Mercurial project on CodePlex.

Now let’s look inside the folder containing the cloned repository. Since the repository is empty, there is only the .hg folder, which stores the Mercurial repository. DO NOT MODIFY THIS FOLDER unless you know exactly what you are doing.

Step 4: Add your files to your local repository

Now you can simply add your files to this folder. In this example, I only have one file that I’m going to add.

Now right-click to bring up the Windows Explorer context menu, and select HG Commit. The HG Commit command will commit to local repository.

HG Commit command

In the HG Commit dialog, fill out the description of the commit. (again this is just for local repository).

Make sure to check to commit all files (or whatever files you want to commit), as illustrated in red below.


Press the Commit button, accept any warnings, and you’ll be prompted with a status/success window.

Step 5: Push to CodePlex

To push the code to CodePlex, you’ll need to open the HG Repository Explorer as seen on the Windows Explorer context menu.

On the menu, you’ll see the Push icon. Press this to start the push to CodePlex.

Mercurial Push to CodePlex

You will be prompted for your CodePlex credentials at this point. Once you have typed in your CodePlex username and password, you’ll see a success dialog.

Now you can go to your CodePlex project and view the source code tab.

First ever CodePlex Mercurial commit

Comments (9)

  1. apoll0 says:

    Is there a way to move existing Projects from TFS/SVN to Mercurial?

  2. Very nice! 🙂

    Is there a way to convert a project that’s using SVN to a mercurial repository?

  3. Adrian Buehlmann says:

    I’ve just created


  4. KMan says:

    Tortoise* client is always great to use.

  5. Justin Chase says:

    If I had a way to upgrade my existing project to this I would do it in a heartbeat.

    I have been very close to just moving to github a few times due to frustraing svn bridge bugs and even more frustrating TFS "features". Please give me an upgrade path!

  6. Justin Chase says:

    I opened a work item on CodePlex for the project switch feature and they closed it and told me to just send them an email via the Contact form for now. So if you want your project upgraded just go here:

    Make sure you’re signed in and ask for them to upgrade the project. Make sure to add your projects name in the body!

  7. Alex Beston says:

    Great tutorial! got me started. thanks!

  8. Even Mien says:

    Here's a link to the ignore file that Rob Connery used:…/mercurial-hgignore-for-visual-studio-2008-projects