Setting up a Mercurial VCS on Ubuntu

Tagged as Linux

Written on 2008-04-22 17:47:37

I've been meaning to set up a Version Control System for a long time now. VCS as a concept has been around for a while but recently a new paradigm in VCS called DVCS (for distributed version control system) has emerged. This new paradigm has cured or at least mitigated the warts of the old "centralized" version control systems and brought new benefits. The thing is there hadn't been a dominant VCS up until now and though some would argue to the contrary I would claim there still isn't. This article strives not to be concerned with the choice of a DVCS. The truth if you choose any of the 4 relatively high-profile DVCS systems that exist today (darcs, bazaar, mercurial, or git) you'll be able to migrate between any of them later without too much difficulty if you change your mind. I was initially leaning towards bazaar or git but eventually settled on (and am thus far quite happy with) mercurial. If you must know some of my reasoning I find that Dave Dribin has captured something close to my opinions.

So, the three things I'd like to cover in this article are mostly covered in two or so places on the mercurial site. I thought I'd group it all together here for simplicity and future reference. The three things I'll be covering are the initial setup including installation and repository creation, making that repository accessible via web browser through a cgi script, and then setting up some authentication to allow you to push changes over HTTP. Let's get started!

Initial Setup
Installation of the software is really straightforward on Ubuntu (see the mercurial site for other installs). Just run
sudo apt-get install mercurial and you're done. You'll have to set one thing in your configuration file before you can make your repository. Insert the following in ~/.hgrc with nano:

[ui]
your_username = FirstName LastName

Your next step of course will be to create a repository. For this, I assume you have some code you'd like stored. I make no claims about what will happen if you try creating an empty repository. It is also worth noting that mercurial tracks content, not files, so it won't carry empty directories. You can work around this on Linux by dropping a hidden file in the directory like so: touch dirname/.hidden.
Once you've done that navigate to the directory you'd like the repo to be in and run the following commands:

hg init
hg add
hg commit

This should bring up nano for you to enter a commit message into describing what changes you're making. Type in a message, save and exit nano. Now you can check and see if this was successful with hg log. If there are no changes listed or exiting nano generated an error you should check your file permissions and see if entering the [ui] information in another config file (perhaps /etc/mercurial/hgrc) fixes the problem.

Setting up the Web Server
I'm assuming that you already have a working repo (naturally) and an install of apache at this point. If you don't have the apache install try running sudo apt-get install apache2. There should be a copy of the cgi script mercurial uses in /usr/share/doc/mercurial/examples/. Copy that to /var/www/cgi-hg/ and rename it index.cgi, then open it up with nano. Around the the third to last line (under def make_web_app) you should see something like:

return hgweb("/path/to/your/repo", "Your Repo Description Here")

Fill in those values with your information but preserving the quotation marks. Also make sure to remove the comments (#s) before import os and import sys. Finally, be sure to run sudo chmod a+x index.cgi on the file so that Apache can execute it. You'll need to edit your apache config file so fire up nano again and open /etc/apache2/apache2.conf to insert the following:

Alias /code /var/www/cgi-hg

DirectoryIndex index.cgi
AddHandler cgi-script .cgi
Options ExecCGI
Order allow,deny
Allow from all


Finally, restart the server with sudo /etc/init.d/apache2 restart and try navigating your web browser to yourdomain.com/code.

Adding Push Support
Use nano to open your_repo/.hg/hgrc (not ~/.hgrc) again. This time we're putting in the server configuration and it should look something like this:

[web]
allow_push = your_username
push_ssl = false

Now you'll have to set up a file to hold the passwords for the users you want to allow to upload changes. To create it and add the first user and password run sudo htpasswd -c /etc/apache2/hg.pass your_username but make sure to omit the -c argument when adding new users in the future or the file will be overwritten. Then you'll need to set up apache to check this information. Open /etc/apache2/conf.d/hg.conf in nano and add the following:


AuthUserFile /etc/apache2/hg.pass
AuthGroupFile /dev/null
AuthName "Your Repository Name"
AuthType Basic

Require valid-user



Save and exit nano. You'll need to change the permissions on the repo tree to allow apache to write to it so run sudo chown -R www-data:www-data /path/to/your/repo and then restart the apache server again. That's it! Time to test it...

***BONUS ROUND***
To test your setup, go to another computer and use apt-get to install mercurial and set your username in the ~/.hgrc. Then run hg clone http://yourdomain.com/code and you should see mercurial make a clone off of your server. Open one of the cloned files and make a small edit or add some new files, whatever you like. When you're done run hg add and hg commit remembering to add commit messages. If you need to delete a file do it through hg remove filename. Finally, try pushing your changes back to the server by running hg push http://yourdomain.com/code. You should get asked for a username and password and if you give valid login information your changes should push through. Now navigate to http://yourdomain.com/code in the browser and see if the changes show up. If they do, you're off to the races.

• ← Previous
• Next →