hg-serve
Serve Mercurial repositories over HTTP
TLDR
Start a web server instance
Start a web server instance on the specified port
Start a web server instance on the specified listening address
Start a web server instance with a specific identifier
Start a web server instance using the specified theme (see the templates directory)
Start a web server instance using the specified SSL certificate bundle
SYNOPSIS
hg serve [OPTION]...
PARAMETERS
-p PORT, --port PORT
Specifies the port number to listen on. Defaults to 8000.
-A ADDR, --address ADDR
Specifies the address to bind to. Defaults to `0.0.0.0` (all available interfaces).
-d, --daemon
Runs the server in the background as a daemon process.
--pid-file FILE
Writes the process ID (PID) of the server to the specified file when running as a daemon.
--webdir DIR
Serves all Mercurial repositories found within the specified directory, creating a list of repositories on the home page.
--repo REPO
Serves a specific repository located at `REPO`. Can be used multiple times, implying `--webdir` if more than one is specified.
--base-url URL
Sets the base URL for links generated by the server, useful when the server is behind a reverse proxy.
--disable-push
Disables push operations to the served repositories, making them read-only.
--disable-pull
Disables pull operations from the served repositories (useful for mirroring or specific read-only scenarios).
--allow-push USERS
A comma-separated list of usernames explicitly allowed to push. Requires external authentication to identify users.
--allow-pull USERS
A comma-separated list of usernames explicitly allowed to pull. Requires external authentication to identify users.
--access-allow IP
Allows access only from the specified IP address or network range (e.g., `192.168.1.0/24`). Can be repeated for multiple allowed sources.
--access-deny IP
Denies access from the specified IP address or network range. This rule takes precedence over `--access-allow`.
--certificate FILE
Path to the SSL/TLS certificate file (e.g., `server.pem`) for enabling HTTPS.
--key FILE
Path to the SSL/TLS private key file (e.g., `server.key`) for enabling HTTPS.
--access-log FILE
Writes web server access logs to the specified file, detailing incoming requests.
--error-log FILE
Writes web server error messages and diagnostic information to the specified file.
-C SECTION.NAME=VALUE, --config SECTION.NAME=VALUE
Sets a Mercurial configuration value for the server process, overriding values from configuration files.
--name NAME
Sets the display name for the served repository in the web interface, useful for `--repo` or single-directory serves.
DESCRIPTION
The hg serve command launches a lightweight, built-in web server to make one or more Mercurial repositories accessible via HTTP or HTTPS. It's designed for quick and easy sharing of repositories, local browsing, or simple collaborative setups, without the need for a full-fledged web server like Apache or Nginx.
When run, hg serve starts a server that allows clients to clone, pull, and potentially push changesets to the served repositories. It provides a basic web interface for browsing commits, files, and other repository contents. By default, it serves the current working directory as a single repository, but it can be configured to serve a specific repository or an entire directory containing multiple repositories.
While highly convenient for development, testing, and small teams, hg serve is generally not recommended for high-load production environments due to its basic security features and limited scalability compared to dedicated web servers combined with Mercurial's `hgweb.cgi` or `hgweb.wsgi` scripts.
CAVEATS
hg serve is intended for simple, ephemeral use or within trusted networks. It lacks advanced security features, robust logging, and performance optimizations typically found in production-grade web servers. For public-facing or high-traffic scenarios, it is strongly recommended to use a dedicated web server (like Apache or Nginx) combined with Mercurial's `hgweb.cgi` or `hgweb.wsgi` scripts, which offer more control over authentication, authorization, and scalability. Direct user authentication is not built-in; `--allow-push` and `--allow-pull` often rely on external authentication (e.g., via a proxy server) or user entries in `hgweb.config`.
AUTHENTICATION AND AUTHORIZATION
hg serve provides basic IP-based access control via `--access-allow` and `--access-deny`. For user-specific authentication and authorization (e.g., allowing specific users to push), it typically relies on external mechanisms. While `--allow-push` and `--allow-pull` options exist, they are often paired with an `hgweb.config` file or an HTTP proxy that handles authentication (e.g., HTTP Basic Auth) to identify users. hg serve itself does not manage user accounts, focusing on serving content.
HTTPS USAGE
To serve repositories over HTTPS, you must provide valid SSL/TLS certificate and key files using the `--certificate` and `--key` options, respectively. For example: `hg serve --port 443 --certificate mycert.pem --key mykey.key`. Ensure the certificate and key files are correctly formatted, are readable by the user running the command, and that the specified port is not blocked by a firewall.
HISTORY
The `hg serve` command has been a fundamental part of Mercurial since its early development. It was introduced to provide a convenient, lightweight way for developers to quickly share their repositories without needing to set up complex web server configurations. While `hgweb` (which uses CGI/WSGI with a full web server) existed for more robust deployments, `hg serve` filled the gap for immediate local testing, ad-hoc collaboration, and sharing within a small, trusted group. Its simplicity and ease of use have made it a popular choice for quick prototyping and demonstration purposes.