Mercurial

Mercurial, commonly referred to as Hg (the symbol for the element Mercury), is an open source distributed version control system.

See also

Bazaar, Git

Installing Mercurial

It’s easy to install Mercurial. To install Mercurial:

1. Open an SSH session to your account.

2. Enter easy_install Mercurial and press Enter.

   Note

   You can specify which Python version to use to install Mercurial by entering easy_install-X.Y Mercurial where X.Y is a Python version number. For example, to use Python 2.5, enter easy_install-2.5 Mercurial.

3. Open ~/.hgrc in a text editor.

4. Add the following lines to ~/.hgrc:

   [ui]
   username = name <your_email_address>

   subtituting name and your_email_address with the name and email address you would like to have appear by default in commits made from your Mercurial installation.

5. Save and close the file.

You can now use the command line tool hg to work with Mercurial repositories. Enter hg help and press Enter for a complete list of commands. To learn more about using Mercurial, check out the official Quick Start guide and the Mercurial book.

Publishing Mercurial Repositories to the Web

You can create an application to serve hgwebdir.cgi (also known as HgWeb), which makes it easy to view repositories with a web browser, as well as push and pull changes over HTTPS.

Note

These directions assume you already have Mercurial installed. If you have not already installed Mercurial, please see Installing Mercurial.

Create an Application to Serve hgwebdir.cgi

The first step in serving Mercurial repositories is to create an application to serve the CGI script.

1. Log in to the WebFaction control panel.
2. Click > Domains / websites ‣ Applications. The Apps list appears.
3. Click the Add new () button. The Add page appears.
4. Enter a name for your application in the Name field.
5. In the App category menu, click to select Static.
6. Click the Create button. The app will be created and the View page appears.

Create a Place to Store Mercurial Repositories

Next, a directory needs to be created where the repositories themselves will be stored. Typically, this will be a directory outside of the Static/CGI/PHP application’s directory.

1. Open an SSH session to your account.
2. Create the repository directory. Enter mkdir ~/directory_name and press Enter. For example, enter mkdir ~/hg and press Enter.

Download and Install hgwebdir.cgi

Now, download the Mercurial sources, which contain a CGI script which will make repositories available on the Web.

1. Open an SSH session to your account.
2. Change to the Static/CGI/PHP application’s directory. Enter cd ~/webapps/static_cgi_php_app_name/ and press Enter.
3. Remove the existing index.html. Enter rm index.html and press Enter.
4. Download the Mercurial sources. Enter wget http://selenic.com/repo/hg-stable/archive/tip.tar.bz2 and press Enter. An archive named tip.tar.bz2 is created in the current directory.
5. Decompress the archive. Enter tar -xvf tip.tar.bz2 and press Enter. A new directory named Mercurial-stable-branch--hexadecimal_number is created in the current directory containing the contents of the archive.
6. Copy Mercurial-stable-branch--hexadecimal_number/hgwebdir.cgi to the current directory. Enter cp Mercurial-stable-branch--hexadecimal_number/hgwebdir.cgi . and press Enter.
7. Remove the archive directory. Enter rm -r Mercurial-stable-branch--hexadecimal_number and press Enter.
8. Remove the archive. Enter rm Mercurial-stable-branch--hexadecimal_number.tar.bz2 and press Enter.

Configure hgwebdir.cgi

Now, configure hgwebdir.cgi so it knows where to look for your Mercurial installation and repositories.

1. Open an SSH session to your account.

2. Change to the Static/CGI/PHP application’s directory. Enter cd ~/webapps/static_cgi_php_app_name/ and press Enter.

3. Make hgwebdir.cgi executable. Enter chmod u+x hgwebdir.cgi and press Enter.

4. Open hgwebdir.cgi in a text editor.

5. If you installed Mercurial with a Python or easy_install version other than the default, edit this line:

   #!/usr/bin/env python
   

   by replacing python with pythonX.Y, where X and Y are the major and minor version numbers of Python, respectively.

6. Uncomment these lines:

   #import sys
   #sys.path.insert(0, "/path/to/python/lib")
   

   and replace "/path/to/python/lib" with the path to the directory where you installed Mercurial. If you used the default easy_install, this directory will be /home/username/lib/python2.4.

7. Save and close the file.

8. Open a new file named hgweb.config.

9. Edit the file so that it looks like the following:

   [paths]
   / = /path/to/repositories/**

   where /path/to/repositories is the path to your Mercurial repositories (for example, /home/username/hg).

   Note

   The asterisks (*) are required for hgwebdir.cgi to find your repositories; they permit hgwebdir.cgi to find Mercurial repositories which are in a subdirectory of the path specified.

10. Save and close the file.

Configure Apache to Use hgwebdir.cgi

The next step in publishing your Mercurial repositories is to instruct Apache to use hgwebdir.cgi to respond to requests.

1. Open an SSH session to your account.

2. Change to the Static/CGI/PHP application’s directory. Enter cd ~/webapps/static_cgi_php_app_name/ and press Enter.

3. Open a new file named .htaccess.

4. Edit the file so that it looks like the following:

   Options +ExecCGI
   RewriteEngine On
   # / for root directory; specify a complete path from / for others
   RewriteBase /
   RewriteRule ^$ hgwebdir.cgi  [L]
   RewriteCond %{REQUEST_FILENAME} !-f
   RewriteCond %{REQUEST_FILENAME} !-d
   RewriteRule (.*) hgwebdir.cgi/$1  [QSA,L]

   Note

   If you will not be hosting your repositories from the root URL path, replace RewriteBase / with RewriteBase /path/to/directory. For example, if you were to host your repositories at http://www.example.tld/hg you would substitute RewriteBase / with RewriteBase /hg.

5. Save and close the file.

Create a Website Entry for the Mercurial Repositories

Finally, it’s time to create a website entry so that requests can be proxied from a URL to hgwebdir.cgi‘s application.

1. Log in to the WebFaction control panel.
2. Click > Domains / websites ‣ Websites. The Sites page appears.
3. Click the Add new button (). The Add page appears.
4. Enter a name for the website entry in the Name field.
5. Click to select Https.
6. Click to select a domain from the Subdomains field.
7. Click the Add new button (). An additional row in the Site apps table appears.
8. Click to select your Static/CGI/PHP application from the App menu.
9. Enter a URL path in the URL path field. If you did not change the contents of .htaccess from the version suggested in Configure Apache to Use hgwebdir.cgi, enter /.
10. Click the Create button. The View page appears.

You can now visit the domain and path specified in the website entry to see your Mercurial repositories. The listing is probably empty now, however; create new repositories with hg init in your repository directory to populate the list.

Secure and Push to Repositories Served by hgwebdir.cgi

Now that you have a working repository browser, you can enable pushing to those repositories over HTTPS for authenticated users.

1. Open an SSH session to your account.

2. Change to the Static/CGI/PHP application’s directory. Enter cd ~/webapps/static_cgi_php_app_name/ and press Enter.

3. Open .htaccess in a text editor.

4. Add the following lines to the bottom of .htaccess to permit pushes only by authenticated users:

   AuthType Basic
   AuthName MyHgWebDir
   AuthUserFile /home/<username>/webapps/<static_cgi_php_app>/.htpasswd
   <Limit POST PUT>
       Require valid-user
   </Limit>
   
   <Files ~ "^\.ht">
       Order allow,deny
       Deny from all
   </Files>

where <username> is your username and <static_cgi_php_app> is the name of the Static/CGI/PHP application.

Note

Alternatively, you can use the following lines to prohibit all access except for authenticated users:

AuthType Basic
AuthName MyHgWebDir
AuthUserFile /home/<username>/webapps/<static_cgi_php_app>/.htpasswd
Require valid-user

<Files ~ "^\.ht">
    Order allow,deny
    Deny from all
</Files>

1. Save and close the file.

2. Now, create an initial username and password that can push to the repositories. Enter htpasswd -c .htpasswd username and press Enter. A prompt appears for a password.

3. Enter the password for the new user and press Enter. A prompt to confirm the password appears.

4. Enter the password again and press Enter.

5. Open hgweb.config in a text editor.

6. Add the following lines to the file:

   [web]
   allow_push = *

   Note

   Alternatively, you can replace * with a comma separated list of users authorized to push. Or, for more finely grained control, you can add these lines on a repository-by-repository basis in the repositories’ .hg/hgrc file.

7. Save and close the file.

You can now push to the repositories as an authenticated user.