Rapid Repository Sharing with Mercurial's hg serve

The Problem: Ad-hoc Collaboration Friction

You have a local Mercurial repository and a teammate needs to inspect a specific feature branch or pull a set of changes immediately. Setting up a dedicated server—complete with SSH keys, HTTP daemons, or a hosted platform—is overkill for a one-off exchange. You need a way to make your local data accessible without forcing your colleague to install complex infrastructure or wait for a sysadmin to provision a server.

The Solution: hg serve

The hg serve command transforms any Mercurial repository into a lightweight HTTP server. It allows other users to browse the repository via a web browser or interact with it using a standard Mercurial client via hg clone or hg pull. Because it is built directly into the Mercurial binary, there is no separate server software to install or configure.

Core Capabilities

• Zero-Client Setup: Anyone with a browser can view the commit history and file diffs.
• Standard Protocol: Uses HTTP, making it compatible with most corporate firewalls and standard hg clients.
• Flexible Porting: Can be bound to any available TCP port, avoiding conflicts with existing services.
• Basic Access Control: Supports simple authentication configured via the local .hg/hgrc file.

Worked Example: Sharing a Local Project

Assume you are working in a repository located at /home/dev/project and want to share it on port 8080 for read-only access.

1. Start the server: Run the following command from within your repository directory. This requires standard user permissions for the directory and the ability to bind to the chosen port.

   cd /home/dev/project
   hg serve -p 8080

2. Verify Accessibility: Open a browser and navigate to http://localhost:8080. You should see the Mercurial web interface displaying the repository's branches and recent changesets.
3. Clone from a remote machine: A teammate on the same network can now clone the repository using your IP address:

   hg clone http://<your-ip-address>:8080/ project-clone

Enabling Push Access

By default, hg serve is read-only. To allow teammates to push changes back to you, modify your .hg/hgrc file before starting the server:

[web]
allow_push = *

Risk Warning: Enabling allow_push without an SSL/TLS layer (like a reverse proxy) transmits data and credentials in plain text. This configuration should only be used on trusted internal networks.

Trade-offs and Limitations

While convenient, hg serve is not a replacement for a production-grade version control host.

Feature	hg serve	Dedicated Server (e.g., hgweb)
Concurrency	Low (Single-threaded)	High (Multi-threaded/Async)
Permissions	Basic/Global	Granular/Per-user
Persistence	Ephemeral (Process-based)	Permanent (Service-based)

If your repository experiences high traffic or requires strict permission auditing, move the repository to a permanent server and use hgwebdir behind a production web server like Nginx or Apache.

Verification and Rollback

To verify the server is active, run netstat -an | grep 8080 (on Linux/macOS) to ensure the port is listening. To stop the server and remove the HTTP access point, simply terminate the process using Ctrl+C in the terminal where the command was executed. This operation does not change the state of your repository data, only the network accessibility.