TortoiseHg Tutorial

- Posted by

In order to use Mercurial, you'll need a client to interact with the repositories on our server. If you're on Windows or Debian (and hopefully Mac in a few months), you should use TortoiseHg. It has a polished interface, all the tools you'll need, and great integration with Windows Explorer/Gnome Nautilus. You can download it from here: http://tortoisehg.bitbucket.org/download/index.html.

Once you install it and restart your computer, you can now use TortoiseHg just by right-clicking anywhere in Explorer*! Here's a quick sample project to demonstrate the basics. It will be similar to Joel Spolsky's tutorial http://hginit.com, but simpler and geared toward the parts of TortoiseHg that we use in GCS.

*Apparently if you use the Libraries feature of Windows 7, the TortoiseHg context menu entry won't appear when you right click on blank space.

Sample project: Awesome

If you're setting up the repository for the first time, you'll need to initialize the repository on the server before anything else.
ssh awesome@gamecreation.org (where "awesome" is the name of your project)
If this is your first time logging in, you may have to change your password. Once you log in, use this command to set up a Mercurial repository in your home directory:
hg init hg
This will initialize a repository in a folder called "hg". Now everyone on your project can use it!

Once you have a working repository on the GCS server, let's move on to the TortoiseHg part. The first thing you'll want to do is clone the repository to your computer. Here are some pretty pictures to demonstrate:

Right click somewhere in Explorer and select the "Clone" option.

The standard read-only URL for our project repositories is: http://hg.gamecreation.org/PROJECT_NAME. If this doesn't work, then let our system admin know! The other URL (which is not read-only, but requires a password) is ssh://PROJECT_NAME@gamecreation.org/hg

Once TortoiseHg finishes cloning the repository, you should see it in Explorer, with the green checkmark showing that it's up to date.

Before we can do anything with the repository, we should make sure we set some settings. First, go to "Explorer Extension Settings".

Scroll through the Sub menu items to select "Synchronize", then press "<- Top" to add it to the context menu. This will be one of your most frequently used commands, so this will save you some time!

Then, go to "Repository Settings", and click on the "Commit" tab.

Enter a meaningful username - andrewid followed by email seems appropriate. Now, click on the "Synchronize" tab, and select "update" in the pulldown menu next to "After Pull Operation".

In Mercurial, when you pull changes from the server's repository, the changes don't immediately go into effect in your local working directory. For the sake of convenience, selecting "update" will make sure your working copy is always up to date.

While you're still in the "Synchronize" tab, if there is a default repository path, select it and click Edit; if not, click Add. Because you will not be able to push changes through the http read-only path, changing this to the ssh path will make sure you always have a secure connection. The format for this path is ssh://PROJECT_NAME@gamecreation.org/hg.

Now you have edited all of the essential options, and can start to work in your repository! I created a todo list, called TODO.txt, and added some text to it. Mercurial doesn't know about TODO.txt yet, so I'll add and commit it to my repository. Right click somewhere and click Hg Commit.



In the lower left panel, the file I just created has a question mark under the status column; this means Mercurial doens't know about the file yet. By checking the box, it will add TODO.txt to the repository, and start tracking any changes I make to it. Once you add a commit message and check any files you want to add to the repository, click Commit to check in all of your changes to your local repository.
After you commit changes to your local repository, you need to give your changes to the server. If you right click and go to Hg Synchronize, you'll get options for sending and receiving changes across multiple repositories. Since you want to send your changes, click Push, and if the ssh URL is in the address bar, it will prompt you for your password, and send the changes.

Now, let's edit the file, to make things interesting. Once you've changed a file that Mercurial knows about without committing the change, it will show a red exclamation mark.

I just added a task to the todo list, and now I'd like to commit that change to the repository. Click on "Hg Commit" again.

The lower right panel contains the "diff" for the file selected in the left panel that I'm committing to the repository - it indicates that I added an important entry to the todo list. Now that I've added a commit message, I'll press Commit to confirm the changes in my repository. Now, to push the changes to the server. Go back to "Hg Synchronize" and press "Push" again.

Oh no, exclamation marks and red text! This message, "push creates new remote heads", means that you can't directly apply your changes to the server's repository. This happened because someone else must have modified TODO.txt after the last time I pulled changes from the server, but before I decided to push my changes. In order to fix this, do not use "push -f". All you need to do is pull the changes that are on the server, and merge them with your changes. So, as a rule of thumb: always pull changes from the server before you try to push your changes, because otherwise Mercurial will yell at you.

Now, I'm pulling the changes from the server that some other jerk made while I was editing TODO.txt. Wait, what the hell: "+1 heads"? This means that because someone else's changes happened at the same as mine, the repository branched. There are now two states: one with my changes, and one with some other guy's. Let's get a better picture of what's going on so we can merge them together. Right click somewhere in Explorer, and select "Repository Explorer".

If you can see the funky looking tree to the left, that's the current state of our repository. If you select the uppermost change in the repository, you can see who did it and what the change is. In order to merge the other change with the changes in the local repostory, right click the other changes and select "Merge with...".

This will let you merge the two changes, and go on your merry way. Before you click "Merge", take a look at "Merge tools:" all the way on the right, and see what tools are available to you. TortoiseHg will let you select different merging programs to get the job done, and in our case we'll just stick with the default that comes with TortoiseHg: TortoiseMerge. If you're on Linux or Mac, you may want to look up "kdiff3" as an alternative.

This is the TortoiseMerge interface, which will show you the two versions of the files, and what you'd like the resulting merged file to be at the bottom. Apparently, SOMEONE thinks we're partying too hard. So, we'll fix that.

If you right click on the right side, you can select blocks of text that you'd like to use in order to resolve the conflict. We also might want to use some of their changes in our merge, so we can actually directly edit the resulting merged file in the bottom.

Now that the file in the bottom is satisfactorally merged, click save, then close TortoiseMerge.

TortoiseHg will happily declare that the files were merged successfully. Hooray! Some ways this might not happen so easily is if you still have more files to merge, or if TortoiseHg wants to confirm that you want to discard the other changes. Either way, once you're done merging, go ahead and click "Commit". Now that you've merged your changes with the other ones in your repository, you'll want to actually share them with the world!

Leave a comment for the commit, and review the diffs to make sure you've merged the files correctly. Looks good, so click "Commit (-1 head)". Phew, we finally chopped off that stray head on our repository.

And for awesomely unknown reasons, TortoiseHg gave our merged repository a gold star for excellence! As you can see, our repository is now fully merged, and ready to push to the server, so go back to Hg Synchronize.

Now, push the merged changes to the server, so it knows you were able to come up with a compromise.

And that's it for the demonstration! Resolving changes is basically as hard as Mercurial gets, and you should be very happy you don't have to do this in SVN or CVS. If you're ever unsure of error messages that Mercurial gives you, or want to do something other than clone, commit, push, pull, or update, you should definitely read the in-depth Mercurial book here: http://hgbook.red-bean.com/read/.

Hopefully you were able to learn the basics of Mercurial and TortoiseHg by reading along that demonstration! If you want one written by someone who is actually awesome (but uses the Mercurial command line interface, instead of TortoiseHg), go back and read http://hginit.com. Between the two tutorials, you should have a pretty good sense of the basics of Mercurial.

If you have any further questions about Mercurial, be sure to post on the forums or send one of the officers an email!