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

To install Mercurial:

  1. Open an SSH session to your account.

  2. Enter easy_install-X.Y Mercurial, where X.Y is the Python version to use to install Mercurial, and press Enter.

    For example, to install Mercurial with Python 2.5, enter easy_install-2.5 Mercurial and press Enter.

  3. Create a .hgrc configuration file, if it does not already exist. Enter touch $HOME/.hgrc and press Enter.

  4. Open $HOME/.hgrc in a text editor.

  5. Add the following lines to $HOME/.hgrc:

    [ui]
    username = name <email>
    

    where name is your name and email is your email address as they will appear in commit messages made from your Mercurial installation.

  6. Save and close the file.

You can now use the command line tool hg 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 possible 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 and Website to Serve hgweb.cgi

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

  1. Log in to the control panel.

  2. Click Domains / websites ‣ Websites. The list of websites appears.

  3. Click the Add new website button. The Create a new website form appears.

  4. In the Name field, enter a website name.

  5. If applicable, in the Machine menu, click to select the server to host the website.

  6. Click to select Encrypted website (https).

  7. For each domain name you want to use with the website, add it to the list of domains. In the Domains field, enter the domain name. Enter one or more domain names. If the domain has not yet been added to the control panel, click the Create link that appears at the bottom of the list of domains to add it.

  8. For each domain name you want to use with the website, add it to the list of domains. In the Domains field, enter the domain name. Enter one or more domain names.

  9. Click Add an application ‣ Create a new application. The Create a new web app form appears.

  10. In the Name field, enter a name for the hgweb.cgi application.

  11. In the App Category menu, click to select Static.

  12. In the URL field, enter the URL path.

    Note

    The first application added to a website is assigned to the root URL path (/).

  13. Click the Save button. The application is installed and added to website’s list of applications.

  14. Click the Save button. The website is created and added to the list of websites.

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 path, where path is the path to a new directory for repositories, and press Enter. For example, enter mkdir $HOME/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 $HOME/webapps/static_app/, where static_app is the name of the static application, 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. Change to the Static/CGI/PHP application’s directory. Enter cd $HOME/webapps/static_app/ and press Enter.

  2. Make hgweb.cgi executable. Enter chmod 711 hgweb.cgi and press Enter.

  3. Make $HOME/webapps/static_app executable. Enter chmod 711 . and press Enter.

  4. Open hgweb.cgi in a text editor.

  5. Configure hgweb.cgi to use the correct version of Python. Edit this line:

    #!/usr/bin/env python
    

    to replace python with pythonX.Y, where X.Y is the version of Python you used to install Mercurial.

  6. 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_app>/hgweb.config"
    

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

  7. 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. Typically, this directory will be /home/username/lib/pythonX.Y, where username is your username and X.Y is the version of Python you used to install Mercurial.

  8. Save and close the file.

  9. Open a new file named hgweb.config.

  10. Configure the path to your repositories. Append the following lines:

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

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

    Note

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

  11. Enable cleaner URLs.

    If the URL path for the application is a root of a domain, append the following lines:

    [web]
    baseurl =
    

    If the URL path for the application is not a root of a domain (for example, www.example.com/hg/), append the following lines:

    [web]
    baseurl = urlpath
    

    where urlpath is application’s URL path (for example, /hg).

  12. Save and close the file.

Configure Apache to Use hgweb.cgi

The next step in publishing your Mercurial repositories is to instruct the Apache web server to use hgweb.cgi to respond to requests.

  1. Change to the Static/CGI/PHP application’s directory. Enter cd $HOME/webapps/static_app/ and press Enter.

  2. Open or edit a file named .htaccess.

  3. 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.com/hg you would substitute RewriteBase / with RewriteBase /hg.

  4. Save and close the file.

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 $HOME/webapps/static_app/ 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_app>/.htpasswd
    
    Satisfy Any
    <Limit POST PUT>
        Require valid-user
    </Limit>
    
    <Files ~ "^\.ht">
        Order allow,deny
        Deny from all
    </Files>
    

    where <username> is your username and <static_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_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 files.

  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.