Mercurial_ The Definitive Guide - Bryan O'Sullivan [47]
Host hg
Compression yes
HostName hg.example.com
This defines a hostname alias, hg. When you use that hostname on the ssh command line or in a Mercurial ssh-protocol URL, it will cause ssh to connect to hg.example.com and use compression. This gives you both a shorter name to type and compression, each of which is a good thing in its own right.
Serving Over HTTP Using CGI
The simplest way to host one or more repositories in a permanent way is to use a web server and Mercurial’s CGI support.
Depending on how ambitious you are, configuring Mercurial’s CGI interface can take anything from a few moments to several hours.
We’ll begin with the simplest of examples, and work our way towards a more complex configuration. Even for the most basic case, you’re almost certainly going to need to read and modify your web server’s configuration.
* * *
High pain tolerance required
Configuring a web server is a complex, fiddly, and highly system-dependent activity. I can’t possibly give you instructions that will cover anything like all of the cases you will encounter. Please use your discretion and judgment in following the sections below. Be prepared to make plenty of mistakes, and to spend a lot of time reading your server’s error logs.
If you don’t have a strong stomach for tweaking configurations over and over, or a compelling need to host your own services, you might want to try one of the public hosting services that I mentioned earlier.
* * *
Web Server Configuration Checklist
Before you continue, do take a few moments to check a few aspects of your system’s setup.
Do you have a web server installed at all? Mac OS X and some Linux distributions ship with Apache, but many other systems may not have a web server installed.
If you have a web server installed, is it actually running? On most systems, even if one is present, it will be disabled by default.
Is your server configured to allow you to run CGI programs in the directory where you plan to do so? Most servers default to explicitly disabling the ability to run CGI programs.
If you don’t have a web server installed, and don’t have substantial experience configuring Apache, you should consider using the lighttpd web server instead of Apache. Apache has a well-deserved reputation for baroque and confusing configuration. While lighttpd is less capable in some ways than Apache, most of these capabilities are not relevant to serving Mercurial repositories. And lighttpd is undeniably much easier to get started with than Apache.
Basic CGI Configuration
On Unix-like systems, it’s common for users to have a subdirectory named something like public_html in their home directory, from which they can serve up web pages. A file named foo in this directory will be accessible at a URL of the form http://www.example.com/username/foo.
To get started, find the hgweb.cgi script that should be present in your Mercurial installation. If you can’t quickly find a local copy on your system, simply download one from the master Mercurial repository at http://www.selenic.com/repo/hg/raw-file/tip/hgweb.cgi.
You’ll need to copy this script into your public_html directory, and ensure that it’s executable.
cp .../hgweb.cgi ~/public_html
chmod 755 ~/public_html/hgweb.cgi
The 755 argument to chmod is a little more general than just making the script executable: it ensures that the script is executable by anyone, and that “group” and “other” write permissions are not set. If you were to leave those write permissions enabled, Apache’s suexec subsystem would likely refuse to execute the script. In fact, suexec also insists that the directory in which the script resides must not be writable by others.
chmod 755 ~/public_html
What could possibly go wrong?
Once you’ve copied the CGI script into place, go into a web browser and try to open the URL http://myhostname/~myuser/hgweb.cgi,