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
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].
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.
allow_archive line tells
hgweb to allow users to download a
.tar.bz2 archive of the repository. You can also add
zip to allow users to download a
.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:
Then, create/edit the file
.hg/hgrc and add the following:
[web] contact = Your Name <email@example.com> 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
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.
- 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)
- 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
- 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
mercurial-server share repositories, so when I push to
mercurial-server, it can be seen on
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,