hg-serve

Start a web server instance

$ hg serve

$ hg serve [[-p|--port]] [port]

$ hg serve [[-a|--address]] [address]

$ hg serve [[-n|--name]] [name]

$ hg serve --style [style]

$ hg serve --certificate [path/to/certificate]

hg serve [OPTION]...

-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.

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.

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`.

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.

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.

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.

hg(1), hgweb(5), hg clone(1), hg pull(1), hg push(1), ssh(1)