Stop Breaking Releases: How Mercurial Stable Numbers Keep Your Builds Sane

You check the logs. The commit history is clean. But the release tags are all over the place. Someone pulled from the wrong branch. Someone else pushed without merging upstream. The version number everyone thought was "the latest"is already weeks behind. Mercurial stable numbers are supposed to stop this from happening.

Mercurial uses stable numbers to give every revision a permanent, unique identifier in the repository. Unlike local revision numbers that change when history rewrites, these stable numbers stick. They are the fixed point you can trust—a reference that stays the same no matter how branches shift or bookmarks move.

When deployed right, stable numbers solve conflicts that happen when working across multiple clones or distributed teams. If you can point to a changeset by its stable number, you know others can find it exactly as it was at that moment in history. You can debug, cherry-pick, or roll back with surgical precision.

The key is understanding how Mercurial generates them. A stable number is tied to the ordering of commits in the repository’s history, not just the branch you have checked out. When a commit enters the repo, it gets assigned the next stable revision number. This number will never change for that changeset in that repository. Even if you reorder commits or strip and reapply them in another clone, the stable number inside that repository stays constant.

This matters for automation. If your CI system tags artifacts with both a stable number and a changeset hash, you can build a release process that’s immune to the chaos of feature merging. No more chasing "release-3"that somehow points to a different commit on two developer machines. Stable numbers pin reality.

But teams go wrong when they confuse global uniqueness with local stability. Stable numbers in Mercurial are repository-local. Two clones of the same repo may assign different stable numbers to the same commit if their commit ordering differs. That’s why hashes are still important—use both. Hashes give universal uniqueness. Stable numbers give human-scale navigation.

The workflow sweet spot is to use stable numbers in day-to-day engineering, like referencing “revision 452” in a conversation, while hashes and tags anchor deployments across systems. Build your process to log both from the start. It’s the fastest way to kill merge confusion and release anxiety.

You can set this up in minutes with the right tooling. See it live. Go to hoop.dev and wire your Mercurial workflow into an environment where stable numbers and hashes work side by side. You’ll end guessing forever.