How To Use Mercurial

Before starting make sure this is setup.

If a project lives somewhere and you want it somewhere else, this is a possible technique for doing that:

Note the weird ssh URL format, the host is separated from the path by the path separator (/). Also note that the path is relative to the home directory. In this example, I’m showing how to lift a repository out of someone else’s home directory as an example of how to get around this overly helpful feature.

Here is how to specify absolute paths.

If you need to use a non-standard port. Here SSH listens to 2020.

If you started the project behind a firewall and want to establish it on your main well-connected server, do something like this from inside the project’s local directory (which will have been set up for hg with hg init etc):

Say you made some changes on a work machine called w and then you came home to a machine called h that you wanted the changes to also be on. First you have to pull the work repository (or you could have pushed before you left).

But that’s not all. Nothing will seem different. The h repository will now be aware that changes have been made, but to actually apply them to the local repository, you need to update that with:

Although these decentralized version control systems have a lot of flexibility, the normal thing is that you have a central storage location and several people work on the same code in several different locations. That is what was just previously described.

But what if you’re working on the code mostly in one location but want to use the source control to distribute it — and of course changes — to multiple hosts. For example, if I have a repo of my unix configuration files, I may want to push that out to various hosts when I’m setting them up. Since that will be constantly being improved in arbitrary places (any host) the system needs to be flexible. This can be done in the following way. Start by creating the remote copy of the repo like this.

It can then be updated from within the repo to the remote location like this.

Obviously there are topology problems if I make different changes to this repo from two remote systems and never coordinate.

Once the remote repo is in action, you can merge any changes made there with a pull.

This prevents the need to log in to the secure central machine from a potentially insecure situation.

You may want to know what version you’re up to.

You may want to even slip this into source code somehow. I’ve used this to generate a that information the way I wanted it.

More details about how you can format such things here.

Sometimes you see evidence of changes when you pull in a repository that someone else (or you elsewhere) is working on.

It is clear that some files changed, but which ones? To find out, use this command.

The worst thing about all of the version control systems is that they are philosophically self-defeating in the sense that if you knew the final organizational structure of all your project’s files, you probably would also know the final exact syntax of the entire project. But the whole point of a version control system is that it manages your lack of this foresight. However, renaming and moving files into completely new directory trees can be a pain.

Sometimes I lose track of which files are being tracked. Check with:

Sometimes I have something on a fancy server somewhere and I pull it in and that’s all well and good. Mercurial makes pushes automatic so it’s easy to forget where that originally was being stored. If I need to check it out into a different place how can I figure out where it came from in a place I’m currently using it?

Sometimes something is done, often to fix a bug, and you wind up making something else not work. You want to go back to the place you "fixed" and revisit that but you can’t remember where it was or what you did. First thing to do is to check the commit logs. I like to reverse them so the newest is last.

This produces a lot of stuff, but if you can find the commit that was around the problem, look for it’s "changeset" id which should look something like: 87:c472394a44cc. The 87 is important here. To see the changes that were made on this commit:

To see just what files were worked on use:

The best summary I have seen is here.

Basically hg revert --all will undo whatever mess you’ve just made, but you can also use --rev to specify a particular revision number.

A good sequence of actions is something like this.

What if you just want to take a look at a previous version to get an idea what you might have messed up?

Sometimes you do a hg push and you get this mysterious message telling you something is wrong.

This probably means that you and the remote team did some changes at the same time. The answer is to merge them.

And it should be fine. Obviously if your merge conflicts, that needs to be sorted out.

Despite the mania for Github, Mercurial is really easy to get on the web and it always has been. The good thing is that you do not need to entrust management of your code to a proprietary company. You can easily host your own repositories. To do so, just be in the tracked directory and do this.

That’s it. Note that this automatically starts its own web server on the spot. It is not daemonized but a process that displays all connection attempts. It can also be put into a cgi-bin directory but that’s a different topic. Now point a web browser to your host like this.

And you can browse away at the change history and the tracked files. The default permissions are read only. To get the whole project, just do something like this from the command line of the receiving system.

Let’s say you have a small group working on a project. They would all like a place which is on 24/7 which can be the main coordinating repository for the group. By renting a $5/month SSH host (or use AWS for free if you’re brave) you can give people personalized access to the repository using SSH keys. Basically the way it works is that all the participants generate an SSH key pair. The public keys are rounded up and put into the hosting service account’s ~/.ssh/authorized_keys file. Instead of giving everyone complete access you can limit the other participants to just being able to work with mercurial. You do this by using the command= directive on the SSH key. Here is an example from the hosting service account’s authorized_keys file.

This is all a one line entry, i.e. replace the \ and returns with nothing. Note that the main repo lives in ourproject in the directory ~/hg.

To use this key from a client somewhere, you’ll need the corresponding private key and the password to decrypt it. Then you must tell mercurial that you don’t want ordinary SSH, you want special key SSH. Like this.

If there are problems check my SSH notes especially the part about "Specifying Commands".