I really like using mercurial-server [lshift.net] for hosting my Mercurial repositories. Because it uses SSH and public keys, it’s quite secure, and works well with multiple users. However, it doesn’t have public access for pulling repositories. For that reason, I also use hgweb (shipped with Mercurial) to make my repositories publicly accessible and pullable, especially with the highlight module (also shipped with Mercurial) that uses Pygments [pygments.org] for syntax highlighting.

So in this post, I’ll be explaining how to use mercurial-server to host your repositories, while also having them publicly browsable and pullable with hgweb. I’ll also be demonstrating how to hide repositories from hgweb, while still keeping them working with mercurial-server.

First, I assume you have a working mercurial-server set up. If you do not, the documentation for it is available here [dev.lshift.net].

To have hgweb serve our repositories, we must first make a configuration file for hgweb. The configuration file should look like this:

[collections]
/var/lib/mercurial-server/repos/ = /var/lib/mercurial-server/repos/

[extensions]
hgext.highlight =

[web]
allow_archive = bz2
pygments_style = vs
style = monoblue

You can, of course, tweak this configuration to meet your needs. The [collections] section should stay the same, however, unless your mercurial-server saves the repositories in a non-default folder.

You can also disable the highlight extension by removing the [extensions] section and the hgext.highlight line. You need to do this, for example, if you do not have the Pygments library installed. However, I highly recommend it for browsing the source code. The pygments_style line should also be removed if you disable the highlight extension. I like the vs style (Visual Studio), but there are quite a few different styles that Pygment has out of the box. If you want to see the styles available to you, run the Python interpreter (python) and run:

from pygments.styles import get_all_styles
print list(get_all_styles())

You can choose between different styles for hgweb as well. I prefer monoblue myself, but there are quite a few options that come with Mercurial, and you can download even more online. If you want to see all of the hgweb styles available, in a shell run:

ls /usr/lib/python*/site-packages/mercurial/templates/
# Note: only the directories are styles!
# If ls does not show colors, try adding the "--color" option.

The allow_archive line tells hgweb to allow users to download a .tar.bz2 archive of the repository. You can also add gz and/or zip to allow users to download a .tar.gz or .zip archive. They are comma-separated, so use bz2, gzip, zip to offer all three.

Next, you should add a contact and description for your repositories. If you don’t, Mercurial will just show “unknown” for Description and Contact. To add them, first change into the repository’s folder:

cd /var/lib/mercurial-server/repos/$REPO_NAME

Then, create/edit the file .hg/hgrc and add the following:

[web]
contact = Your Name <your@email.address>
description = My Mercurial repository

Additionally, for any repository you do not want to be shown in hgweb (which will also prevent people from pulling the repository using hgweb), add the following instead:

[web]
deny_read = *

You also need to set the ownership of the hgrc files to the mercurial-server user, hg. To do that, it’s easiest just to set the ownership of the entire repos folder (which is safe, because mercurial-server always owns the entire folder anyway) by running:

chown -R hg: /var/lib/mercurial-server/repos/
# Failing to do this will cause warnings about untrusted files anytime
# someone pushes or pulls using mercurial-server!

Finally, you need to configure your web server to use hgweb. This part is web server dependent. However, before you configure your web server, you need to choose the interface hgweb will use to communicate with your web server.

• CGI
  • Pros: easy to set up, no overhead when not being used, software updates happen immediately
  • Cons: forks a new process for each request so slightly slower page loads for small requests (insignificant for large requests, such as pulling a repository)
• FastCGI
  • Pros: no forking overhead so each request starts being processed immediately
  • Cons: always running so takes up more RAM, more complex to set up, not officially supported by Mercurial (although a FastCGI script is provided), software updates require a restart of the FastCGI script
• WSGI
  • Pros: no forking overhead like FastCGI, software updates happen immediately
  • Cons: more complex to set up, always running so takes up more RAM, requires either a Python interpreter in your web server (Apache) or a separate process (most other web servers)

No matter what you choose, the setup process is documented here [mercurial.selenic.com]. Remember to point hgweb at the configuration file you created!

The end result should look something like this [hg.0x3b.com]. That installation of hgweb does not support pushing; mercurial-server handles all pushes. However, both hgweb and mercurial-server share repositories, so when I push to mercurial-server, it can be seen on hgweb immediately.

Hopefully this HOWTO was helpful! Feel free to leave comments if you have any questions or concerns. If you have any suggestions, please feel free to leave them here!

Thanks for reading,
dririan