The build kept failing, and no one knew why.
It was 3 a.m., and the logs were useless. Then, buried eight screens deep, sat the culprit: a single Mercurial environment variable, set weeks ago, now pointing the system into a dead end. If you’ve worked with Mercurial long enough, you’ve met its hidden levers—the environment variables that can make or break your workflow. They’re silent, global, and ruthless in their scope.
Mercurial environment variables control everything from authentication to repository behavior to default commands. They can override config files. They can set global repository defaults. They can subtly change clone, update, or commit behavior without leaving a trail in hgrc. What makes them powerful is also what makes them dangerous: they live outside your project. A variable in one shell session can wreck a build in another.
The essentials start with knowing the variables. HGUSER sets your commit author. HGENCODING controls how Mercurial reads and writes text. HGRCPATH redefines where Mercurial looks for its config files. HGPLAIN strips away extensions and defaults for scripting or debugging. Each is a direct line into Mercurial’s operational brain—faster than editing a config, but just as permanent when exported into an environment.
Scope matters. On a local machine, you might set HGUSER for a quick one-off commit. In CI, you might inject HGRCPATH to point to a minimal configuration for builds. In production automation, you might use HGPLAIN to keep runs reproducible. The mistake is leaving them there. Stale values cause mysterious behaviors—especially when multiple repos, branches, or scripts run in the same environment.
When debugging, dump all relevant environment variables before running Mercurial commands. This is one of the fastest ways to spot an unintentional override. And when setting them, prefer passing them inline for single commands—HGPLAIN=1 hg log—rather than exporting them globally. This keeps state contained, predictable, and discoverable.
Standardizing how teams set and clear these variables is worth the effort. Document defaults. Make CI pipelines explicit. Clear them at the start of scripts. Treat them as code, because in practice, they are part of your code’s runtime.
If you want to see this discipline in action—not in a static guide, but live—there’s a way to get it running in minutes. Start managing environment variables, Mercurial config, and repo state inside unified, reproducible sandboxes without touching local dev clutter. See it in action now, start building instantly, and keep your environment clean. Try it at hoop.dev.