Publishing Mercurial Repositories

The easiest way to share changes with other people using Mercurial is to publish them on the Web. Mercurial lets people pull changes using HTTP.

The following two methods are the most recommended for publishing repositories over HTTP:

• Use the hgweb.cgi script. This is a simple way to quickly [#single publish a single repository].

• Use the hgwebdir.cgi script. This lets you [#multiple publish multiple repositories] easily, but initial setup can be a bit of work.

Less desirable are the following:

• Use the hg serve command. This is Mercurial's [:hgserve:built-in Web server]. It is not really recommended except for temporary situations where you need to publish a repository for a few minutes, for example to pull changes from a laptop.

• Make the plain repository available. This uses a much slower, less reliable protocol, called static-http. We won't cover it here, see ["StaticHTTP"] instead.

For private or restricted-access repositories, some other options exist and these are covered elsewhere:

• [:SharedSSH:Shared repositories over SSH]

• HTTPS with authentication certificates
• NFS

TableOfContents(2)

Anchor(introduction)

1. Introduction and Prerequisites

In this document we assume that repositories reside in the /home/user/hg directory. For example, a repository called myproject would reside in /home/user/hg/myproject.

To implement the mechanisms described in this document, you will need the following:

• Some control over the behaviour of the Web server you use.
• (Optional) control over the DNS domain you use.

With control over DNS, such as that provided with various Web hosting service control panels, you should be able to set up a subdomain; this makes the URL of your repositories a little tidier, so that http://hg.example.com/myproject can be used instead of http://www.example.com/hgwebdir.cgi/myproject, for example.

Such an approach, known as virtual hosting, is entirely optional. To implement it for the fictional example.com, a CNAME record for hg.example.com would be defined for the same address as that already used by the Web server.

Anchor(single)

2. Publishing a Single Repository

To publish a single repository, perform the following steps:

1. Find the hgweb.cgi script in the root of your Mercurial source tree.

2. Copy it to a directory that is configured for CGI scripts in your Web server.

3. Rename it to index.cgi if you want, then edit its contents.

If Mercurial is not installed system-wide, uncomment and edit the Python path in hgweb.cgi (or index.cgi) as indicated:

# adjust python path if not a system-wide install:
import sys
sys.path.insert(0, "/home/user/lib")

You will need to edit the call to hgweb.hgweb as indicated in the following example:

h = hgweb.hgweb("/home/user/hg/myproject", "My Project")

While you could use this mechanism to publish multiple repositories, it requires a little work to configure each copy of the script to have slightly different paths.

Anchor(multiple)

3. Publishing Multiple Repositories

The hgwebdir.cgi script takes some work to initially set up, but once it's working, it lets you publish new repositories easily and cheaply. Its advantage is that to publish a repository, you simply place a clone in a particular directory, then add one line to a config file to tell the CGI script that it is allowed to publish that repository.

3.1. Setting up the CGI script

To publish a single repository, perform the following steps:

1. Find the hgwebdir.cgi script in the root of your Mercurial source tree.

2. Copy it to a directory that is configured for CGI scripts in your Web server. This will be illustrated below using /home/user/webdir as this directory.

3. Edit the contents of the file.

If Mercurial is not installed system-wide, uncomment and edit the Python path in hgwebdir.cgi as indicated:

# adjust python path if not a system-wide install:
import sys
sys.path.insert(0, "/home/user/lib")

3.2. Setting up the hgweb.config File

In the /home/user/webdir directory, create a file called hgweb.config. Here are the contents of an hgweb.config file:

[paths]
myproject = /home/user/hg/myproject
otherproject = /home/user/hg/otherproject

This file tells the CGI script which repositories it is allowed to publish and how their published locations map to their actual locations in the filesystem. Note that the keys (on the left) can be paths incorporating / characters, and that the values (on the right) can be relative paths to locations within the CGI directory.

4. Configuring Apache

There are many ways of configuring Apache to run CGI scripts, and a few of the possibilities are provided below. Where the main configuration files are mentioned, you should use the appropriate conventions for your system in defining such files in the conf.d and/or sites-available directories.

In each example, hgwebdir.cgi is mentioned, but the same principles apply to directories hosting the hgweb.cgi script.

4.1. Using a Simple CGI Directory

This example requires access to the main configuration files.

Here is one way that a CGI directory can be configured:

Alias /hg /home/user/webdir
<Directory "/home/user/webdir">
    DirectoryIndex hgwebdir.cgi
    AddHandler cgi-script .cgi
    Options ExecCGI
    Order allow,deny
    Allow from all
</Directory>

This should permit URLs like http://www.example.com/hg/ to show the repository browser, although to hide the hgwebdir.cgi script name in URLs, more work is required (and is mentioned below).

4.2. Using Virtual Hosts

This example requires access to the main configuration files.

Here is an example Apache configuration for publishing repositories at http://hg.example.com/. A description follows the example.

<VirtualHost *:80>
  ServerName hg.example.com

  ServerAdmin webmaster@example.com
  CustomLog logs/access_log.example combined
  ErrorLog logs/error_log.example

  RewriteEngine on
  RewriteRule (.*) /home/user/webdir/hgwebdir.cgi$1

  # Or we can use mod_alias for starting CGI script and making URLs "nice":
  # ScriptAliasMatch ^(.*) /home/user/webdir/hgwebdir.cgi$1

  <Directory "/home/user/webdir/">
    Order allow,deny
    Allow from all
    AllowOverride All
    Options ExecCGI
    AddHandler cgi-script .cgi
  </Directory>
</VirtualHost>

The directives in the above have the following purposes:

• The ServerName directive matches the hostname configured for the domain.

• The next section (ServerAdmin and so on) is just administrative cruft.

• The rewrite-related directives (RewriteEngine and RewriteRule) tell Apache to turn URIs ending in /myproject into /home/user/webdir/hgwebdir.cgi/myproject. This causes Apache to fire up the CGI script, giving it the remainder of the URI as an argument.

• Finally, the Directory section lets Apache know that we have a CGI script to look at.

4.3. Using a CGI Script with Authentication

This example requires access to the main configuration files.

Here's an alternative approach that provides global read-only access to the repositories, but requires authentication for pushing:

ScriptAliasMatch ^/hg(.*) /home/user/webdir/hgwebdir.cgi$1
<Location /hg>
    Allow from all
    Options ExecCGI

    AuthType Digest
    AuthName "Mercurial repositories"
    AuthDigestProvider file
    AuthUserFile /home/user/hg/hgusers
    <LimitExcept GET>
        Require valid-user
    </LimitExcept>
</Location>

You'll need to add writable users to /home/user/hg/hgusers with the htdigest command.

4.4. Using an .htaccess File

This example can be used with pre-configured CGI directories.

If you may not change the main Apache configuration files, you may still be able to use .htaccess file to make URLs nicer, like in the previous section. Here is an .htaccess file which sits in the published webdir directory on the Web server and redirects http://www.example.com/hg/* urls to the hgwebdir.cgi script inside that folder. As a result it would no longer be not necessary to mention the CGI script name in URLs: one could use http://www.example.com/hg/myproject instead of http://www.example.com/hg/hgwebdir.cgi/myproject.

# Taken from http://www.pmwiki.org/wiki/Cookbook/CleanUrls#samedir
# Used at http://ggap.sf.net/hg/
Options +ExecCGI
RewriteEngine On
#write base depending on where the base url lives
RewriteBase /hg
RewriteRule ^$ hgwebdir.cgi  [L]
# Send requests for files that exist to those files.
RewriteCond %{REQUEST_FILENAME} !-f
# Send requests for directories that exist to those directories.
RewriteCond %{REQUEST_FILENAME} !-d
# Send requests to hgwebdir.cgi, appending the rest of url.
RewriteRule (.*) hgwebdir.cgi/$1  [QSA,L]

A corresponding change in hgweb.config can be made to make sure that the nicer urls are used in the HTML produced by the CGI scripts:

[web]
baseurl = /hg

Where the CGI scripts are made to appear at the server root (for example, http://hg.example.com/), leave the baseurl setting blank:

[web]
baseurl = 

Generally, the value specified should not end with a / character.

5. Allowing Push

Make sure that your repository's .hg/hgrc file (or the /home/user/.hgrc file) contains the allowed users:

[web]
allow_push = frodo, sam

This would allow pushing for "frodo" and "sam". You can allow pushing for everyone with

[web]
allow_push = *

5.1. Pushing via http(s) and .htaccess

Create an htpasswd file with htpasswd -c <filename> <username> and enter the desired password for the username. Later, you can add more usernames with htpasswd <filename> <username>.

Add this to your .htaccess file:

AuthUserFile /path/to/htpasswd
AuthGroupFile /dev/null
AuthName "My Repository"
AuthType Basic
<LimitExcept GET>
Require valid-user
</LimitExcept>

By default, pushing is only allowed via https. To permit http pushing you have to add this to your repository's .hg/hgrc file (or to the /home/user/.hgrc file):

[web]
push_ssl = false

6. Troubleshooting

Mercurial is executed on the server by Apache and therefore runs as the Apache user and group. If experiencing flaky behavior, it may be because the CGI script is failing because it does not have enough rights. In that case, you should check the log files, but you can also make some common-sense permissions checks.

There are two ways that problems primarily manifest themselves on the server: either you won't see any repositories at all (indicating missing read or execute permissions) or you won't be able to push to the server (indicating missing write permissions), which gives you the error message:

abort: ‘http://foo/bar’ does not appear to be an hg repository!

The best way to solve permissions problems is to grant the required permissions to the Apache group (e.g. www-data on Debian). You should have some familiarity with assigning permissions under Linux/Unix before attempting the following.

Suppose your main user is "john", your web server runs as "www-data" and your repositories are in "/home/john/repositories". Then, execute the following commands to change the group for all files in your repositories on the server and make the files writable to the server process as well as make the home directory readable.

chown -R john:www-data /home/john/repositories
chmod -R g+rw /home/john/repositories
chmod g+x /home/john/repositories

For each repository, you will have to make both the repository folder and the .hg folder executable as well:

chmod g+x /home/john/repositories/rep1
chmod g+x /home/john/repositories/rep1/.hg

7. Putting Useful Information in the Index Page

If you get everything working properly, pointing a browser at the CGI script directly should give a list of the repositories you've published. This will be a table containing four columns. Let's say you have published a repository named lord/rings. To fill out the first three columns of the index entry for that repository, you will need to edit its .hg/hgrc file, and add a new section:

[web]
contact = Bilbo Baggins
description = My precious!
name = lord/rings

8. Allowing Archive Downloads

Make sure that your repository's .hg/hgrc file (or the /home/user/.hgrc file) contains the allow_archive setting:

[web]
allow_archive = gz, zip, bz2

This example illustrates how gzip, zip and bzip2 archive formats can be supported. As a result, links should appear in the Web interface corresponding to these archive types.

9. What Can Go Wrong?

If the version of hgwebdir.cgi is newer than the version of Mercurial you have installed, you may experience strange results. This could happen if you use a binary installer for Mercurial, and manually fetch hgwebcir.cgi from a source repository. Newer versions of Mercurial support older versions of the cgi scripts, so you usually do not have to upgrade all your cgi installations, though it might be useful.

If you are trying to publish multiple repositories, and you haven't configured Apache to force all accesses to go through the hgwebdir.cgi script, you will not be able to access any of the repositories you have published unless you set up a hgweb.cgi script in each published repository. Clearly, this defeats the whole point of using hgwebdir.cgi in the first place, as you're not saving any effort.

Whatever mechanism you are trying to use, the important thing is to ensure that all accesses go through hgwebdir.cgi, so that Apache can pass the rest of the path to it using the PATH_INFO environment variable.

10. Theming

The hgweb interface is completely themable. See the ["Theming"] page for additional instructions on customizing the look of your site.

CategoryWeb CategoryHowTo