Diff for "PublishingRepositories"

TableOfContents (this page ought to be merged with ServerInstall)

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.

There are four ways to publish a repository over HTTP, of which the two below are most worth considering:

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

• Use the hgwebdir.cgi CGI script. This lets you 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 a multithreaded server since version 0.9. It is not 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.

Publishing a single repository

The hgweb.cgi CGI script is simple to use. You will find it in the root of your Mercurial tree. Copy it to a directory that your web server will handle CGI scripts in, rename it to index.cgi if you want, then edit its contents, and you're done.

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.

Publishing multiple repositories

The hgwebdir.cgi 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.

I will describe the setup that BryanOSullivan (me) and ThomasAH use. To mimic our configurations, you will need the following:

• Control over the web server you use.
• (Optional) control over the DNS domain you use.

Miscellaneous details

1. Is virtual hosting necessary?

Using virtual hosting is entirely optional, and not worth it in the majority of cases. It simply makes URLs a little tidier.

For example, I can serve repositories at http://hg.serpentine.com/mercurial/hg instead of http://www.serpentine.com/hg/hgwebdir.cgi/mercurial/hg.

To do this, I simply have hg.serpentine.com CNAMEd to my web server.

2. Setting up the CGI script

Choose a directory you want to publish from. On my systems, I use /home/bos/hg/share, which you will see below.

Copy hgwebdir.cgi in there. Read and edit it, then create a file called hgweb.config.

3. Setting up the hgweb.config file

Here are the contents of my hgweb.config file:

[paths]
mercurial/bos = mercurial/bos
mercurial/hg = mercurial/hg
mercurial/crew = mercurial/crew
mercurial/tah = mercurial/tah

The duplication above looks a little silly, but it's telling the CGI script which repositories it is allowed to publish.

4. Configuring Apache

Here's the Apache config I use. Description below.

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

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

  RewriteEngine on
  RewriteRule (.*) /home/bos/hg/share/hgwebdir.cgi$1

  # would not this be sufficient instead of this nobody-can-understand-rewrite-thing?
  # ScriptAlias / /home/bos/hg/share/hgwebdir.cgi

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

The ServerName directive matches the hostname I configured earlier.

The next section is just administrative cruft.

The rewrite-related directives tell Apache to turn URIs like /mercurial/hg into /home/bos/hg/share/hgwebdir.cgi/mercurial/hg. 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.

5. Using .htaccess file

If you may not configure apache, you can use .htaccess file to make urls nicer, like in previous section. Here is an .htaccess file which sits in hg/ directory on webserver and redirects http://server/hg/* urls to hg.cgi script inside of that folder, so it is not necessary to use cgi script name in urls, i.e. one can use simple http://server/hg/repo instead of http://server/hg/hg.cgi/repo.

# 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]

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

7. What can go wrong?

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 REQUEST_INFO environment variable.

8. Theming

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