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>
   

   substituting 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 hgweb.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 hgweb.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. In the Name field, enter a name for your application.
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 hgweb.cgi

Now, download hgweb.cgi, 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. Find your Mercurial version number. Enter hg version and press Enter.
5. Download hgweb.cgi for your version of Mercurial. Enter wget http://selenic.com/repo/hg-stable/raw-file/version/hgweb.cgi where version is the version number for your Mercurial installation, and press Enter.

Configure hgweb.cgi

Now, configure hgweb.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 hgweb.cgi executable. Enter chmod 711 hgweb.cgi and press Enter.

4. Make ~/webapps/static_cgi_php_app_name executable. Enter chmod 711 . and press Enter.

5. Open hgweb.cgi in a text editor.

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

7. If you are using a version of Mercurial later than 1.5, edit this line:

   config = "/path/to/repo/or/config"
   

   to this:

   config = "/home/<username>/webapps/<static_cgi_php_app_name>/hgweb.config"
   

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

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

9. Save and close the file.

10. Open a new file named hgweb.config.

11. 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 hgweb.cgi to find your repositories; they permit hgweb.cgi to find Mercurial repositories which are in a subdirectory of the path specified.

12. Save and close the file.

Configure Apache to Use hgweb.cgi

The next step in publishing your Mercurial repositories is to instruct Apache to use hgweb.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 ^$ hgweb.cgi  [L]
   RewriteCond %{REQUEST_FILENAME} !-f
   RewriteCond %{REQUEST_FILENAME} !-d
   RewriteRule (.*) hgweb.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 hgweb.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. In the Name field, enter a name for the website entry.
5. Click to select Https.
6. In the Subdomains menu, click to select a domain.
7. Click the Add new button (). An additional row in the Site apps table appears.
8. In the App menu click to select your Static/CGI/PHP application.
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 hgweb.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 hgweb.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>
   

5. Save and close the file.

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

   See also

   See Strengthening Passwords for important information about choosing passwords.

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

8. Enter the password again and press Enter.

9. Open hgweb.config in a text editor.

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

11. Save and close the file.

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

Troubleshooting

Error: bash: hg: command not found

If you’re cloning, pulling, or pushing from Mercurial repositories via ssh (for example, hg clone ssh://username@username.webfactional.com/path/to/repo), you may encounter an error, bash: hg: command not found, which appears when the remote session is unable to locate the hg script.

To fix this problem:

1. Open your local .hgrc file in a text editor. .hgrc is typically found in your home directory.
2. In the [ui] section, add a new line containing remotecmd = ~/bin/hg.
3. Save and close the file.