How To Use Mercurial

Why not use the near universal other version control system?

Ok, great. Now I have a trusted collaborator who I want to be able to clone this. They actually can get this far on a remote host.

Cool. So now I want to push this change back to the original that the main developer is working on in its primary location. But what happens when I try git push? I get a huge overly complex error message with multiple strange possible work-arounds. The gist of the problem is described in the error message like so.

So I don’t have time to become an expert in what that means. Asking ChatGPT to cut through the cruft, I arrive at the following conclusion.

I would expect git to be fine if you have a central (non-working!) repo living at https://kernel.org or https://github.com but if that’s not how you’re doing things, Mercurial can be the difference between possible and not. I actually couldn’t believe that git was deficient in this way (without onerous esoteric configuration tweaks) but it certainly fails as shown and research to overcome this limitation — perhaps there for some good reason in another context — turned up nothing for me. Maybe I’m just overlooking the easy way to get Git to behave like I want, but I am 100% certain that this putative easy way is not easier than simply using 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 on the less important host, you can merge any changes made there back to the secure main host with a pull.

This prevents the need to log in to the secure central machine from a potentially insecure situation. In summary, push your centralized changes from your secure machine and collect miscellaneous changes on the remote machines by pulling. Avoid authenticating back to your secure machine from random accounts you may have access to.

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.

Mercurial is pretty cool about how it handles binary files. Basically no special treatment for binary files is needed and it the system should be fine.

I wasn’t sure about symlinks, but indeed symlinks are tracked as symlinks. So that’s good to have confirmed.

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".