Mercurial Path Configuration Using $HOME Fails in Production

Answer the question first

Mercurial expands environment variables in paths sections using os.path.expandvars. If $HOME is unset or points to an unexpected directory, the expansion yields an empty or wrong string, and hg pull / hg push fail with “repository not found” or “invalid path”. Mercurial has no built‑in syntax for a fallback value, nor a graceful error message for a missing variable.

Confirmed facts

• Systemd services do not inherit the shell’s HOME unless explicitly set.
• Containerized or CI jobs often default HOME to /root when the user is not defined.
• Mercurial logs contain a message like path expansion failed: $HOME is not defined when the variable is missing.

Likely explanation

The failure is almost always caused by the Mercurial process running under a user whose HOME environment variable is either empty or points to a directory that does not contain the expected repository. This can happen when:

• The service unit omits Environment=HOME=….
• A CI job runs as root in a container where $HOME defaults to /root.
• A developer checks out the repo under a different home directory than the one used by the Mercurial client.

Steps needed for this case

1. Verify the value of HOME when Mercurial starts.
   

   # Run as the service user
   sudo -u mercurial_user sh -c 'echo $HOME'

2. If HOME is empty or wrong, set it explicitly.
   
   • systemd service: add Environment=HOME=/opt/mercurial/repo to the unit file, then systemctl daemon-reload and restart.
   • Container / CI job: export HOME=/opt/mercurial/repo in the job script before invoking hg.
3. Use a wrapper script if you need a conditional fallback.
   Create hg-wrapper.sh:

   #!/usr/bin/env bash
   # Resolve $HOME or fallback
   export HOME=${HOME:-/opt/mercurial/repo}
   exec hg "$@"
   

   Replace direct hg calls with ./hg-wrapper.sh or point the service’s ExecStart to this script.
4. Document the configuration. Add a comment in ~/.hgrc or mercurial.ini explaining the dependency on $HOME and the steps taken to guarantee it.

No syntax for fallback exists in Mercurial

Mercurial’s configuration language does not support conditional expressions or default values like ${HOME:-/default/path}. Therefore, the only reliable approaches are to ensure HOME is set correctly in the environment or to wrap hg with a small script that supplies a fallback.

Upcoming releases

There is no official roadmap item for adding environment‑variable fallbacks or improved error messages for missing variables. Users are advised to monitor the Mercurial project page for any future enhancements.

CI pipelines: a practical pattern

• Define HOME in the job configuration (e.g., export HOME=/opt/mercurial/repo).
• Use hg --config paths.default=$HOME/repo to override the config per run if needed.
• Add a pre‑step that prints echo "HOME=$HOME" to the log for debugging.

Missing diagnostic detail

To refine the recommendation, could you confirm the value (or lack thereof) of HOME when Mercurial runs in the production environment? This will determine whether the issue is purely environmental or if a deeper configuration problem exists.