Keep track of remote names (branches and bookmarks) in Mercurial.

With this extension installed, Mercurial's behavior regarding bookmarks is changed. The core of this extension is to keep track of remote bookmarks and branches and to make a better user experience. It exposes up to three new namespaces based on the branch heads and bookmarks available in other repositories. The three namespaces are:

  • remotebranches: the heads of each branch on the peer repo (default: on)
  • remotebookmarks: the bookmarks from the peer repo (default: on)
  • hoistedbookmarks: a "short name" interface for hoisting a single peer's remote bookmarks into the top-level namespace, allowing workflows to stay the same when referring to bookmarks on the chosen peer (default: 'default')

For example, when you pull from a repository listed in .hg/hgrc's [paths] section, you get output similar to the following:

o  f3d8 @
|  more trunk
o  824e
|  trunk
| o  2b7b feature
| |  feature: more new stuff
| |
| o  a342
|/   feature: new stuff
o    52a8 (smf/default) [smf/@]
|\   merge stable into default
| |
| o  9c95
| |  chug along trunk
| |
o |  ea15 stable (smf/stable)
| |  fix for stable

What this output is showing is that the head of the default branch in a repo at path smf is 52a8. This is labeled above as (smf/default). Similarly, the bookmark @ was last seen on smf at the 52a8 changeset. Both remote names cannot move unless you push or pull from the remote server.

Remote names are discovered by sending a single extra request to the Mercurial server after a push or pull is complete. This extension works properly with paths from the schemes extension included with Mercurial. Other extensions which perform varying kinds of manipulation on the repository path may not function as expected.

This extension is built on top of the Mercurial namespace API introduced in 3.3.


To enable the extension, you must add an entry to the [extensions] section of your hgrc file:

remotenames = /path/to/hgremotenames/

Behavior Changes

Expect changes. Most features are enabled by default to give you an idea of the possibilities available with this workflow.

Since this extensions keeps track of remote bookmarks, we no longer clone or pull remote bookmarks by default. Therefore, pulling from a remote server will no longer update your local bookmarks. This has the rather large beneficial side-effect of completely eliminating bookmark divergence, a complicated and difficult concept to understand, explain, and work with.

The commands bookmarks, branches, and log all gain a --remote flag to display remote names. This will also unhide obsolete changesets if you are working with the Changeset Evolution extension.

Another big behavior change is that of a bare hg push. For changesets that do not create a new remote head AND are only reachable by a local bookmark, hg push will abort and not push these changesets. Hopefully, this is behavior is clear with the following example:

hg clone foo
cd foo
hg book feature
# <hack, hack, hack>
hg push
pushing to foo
searching for changes
abort: push creates new anonymous head without the bookmark: 'feature'
(use 'hg push -B feature' to create a new remote bookmark)

This behavior change is intended to prevent accidentally pushing an unnamed ('anonymous') head to a remote repository. To enforce this style of workflow, read about the forceto configuration option below.

Cloning and Pulling

As mentioned above under the Behavior Changes section, pulls by default will not sync normal bookmarks between the two repositories. This is also the case with cloning. In effect, bookmarks in the remotenames world are no longer a shared namespace among peers; rather, they are distinct namespaces that need to be manually and explicitly synchronized among peers during pull operations. During push operations, the manual synchronization can be achieved with the --to option described in the previous section.

To re-enable the bookmark synchronizing behavior on clone and pull, set the syncbookmarks configuration option:

syncbookmarks = True


When pushing changes to another repository, remotenames introduces a new flag, --to (-t) which drastically changes the behavior of push to be more friendly in a remotenames world. The --to flag requires the name of the remote bookmark to push (without any remote/ prefix). For more on hg push behaviour, see the Tracking section. When --to is specified, the default push rev (-r) will be .. Another rev may be specified, but only one rev may be specified or the push will abort. The specified rev, and it's ancestors, will be pushed to the remote repository, and the remote repository will have the named bookmark updated to point to this revision, subject to the following constraints (unless --force/-f is specified):

  • The remote bookmark must already exist (it will be created with -f)
  • The remote bookmark rev must exist in the local repo (subset of the below)
  • The pushed rev must be a descendant of the current remote bookmark
  • A special case of the above: the remote bookmark already points at rev

Using --to also disables other flags to avoid confusion. hg push --to will abort if any of the following flags are specified:

  • --bookmark / -B
  • --branch / -b
  • --delete / -d

There is a new config option to enforce using --to if that is appropriate in your chosen workflow. To enable it, set the option forceto:

forceto = True

In this mode, to push revs to a peer, you must specify a name with the --to flag. You can still delete a remote bookmark in this mode with the added --delete flag to push as well.

Finally, there is another new flag for push, --delete, which allows remote bookmark to be deleted without deleting any local bookmark or pushing any revs.


Remotenames adds up to four new template keywords: remotebranches, remotebookmarks, remotenames (a combination of the first two), and hoistedbookmarks, which are up to one peer's remote bookmarks, lifted into the main namespace (eg, not requiring a pathname prefix).

For example, the diagram in the introduction above uses the template ({remotebranches}) [{remotebookmarks}]. Alternatively, you could use remotenames to include both namespaces. If you set the configurable option suppressbranches:

suppressbranches = True

Then remotenames will only display the branch name if there is no bookmark present on the same node.

Aliasing and Renaming Paths

For the example in the Introduction, the name smf is used instead of default because the .hg/hgrc is as follows:

default =
smf =

Since those two paths are equal, the non-default name is chosen. This effect can also be achieved by using the 'rename' configuration option:

[remotenames] rename.default = smf

Mercurial has several overloaded terms, including ther word default which can refer to the implicit named branch or the clone source path. Since remotenames uses the peer's path name, it is common to see remotenames prefixed with default/. This can be confusing since branches also often have that name. Therefore, remotenames allows you to rename a path to something else. One common choice is to rename default to remote. Thsi would result in remote names from this repository showing up as remote/bookmark instead of default/bookmark. Push and pull to this name will also work.

Finally, there is an alias.default setting:

[remotenames] alias.default = True

Setting this will drop the remotebranch name smf/default into just smf. It is another way to reduce the nubmer of times that default shows up in the UI.

Transition Helpers

Using remotenames can be a big departure from previous workflows, so in addition to renaming and aliasing, the remotenames extension offers a few other options to make migrating to a remotenames easier. First is the transitionbookmarks configuration option:

[remotenames] transitionbookmarks = @


With this setting, remotenames will delete the local bookmarks @ and foo the first time the extension is run (and pulls the remotenames from a peer). In order to prevent these bookmarks from being re-created and causing confusion, you can set the disllowedbookmarks config:

[remotenames] disallowedbookmarks = @


At which point mercurial's bookmarks command will refuse to create new bookmarks with these names.


Remotenames makes the following new revsets available: pushed(), upstream(), remotebranches(), remotebookmarks() and remotenames(). The pushed() revset returns all revisions that are have been pushed to any repository tracked by remotenames. The upstream() set is those revisions which are in a repository whose path is listed in the upstream field of the [remotenames] configuration section. If there is no remotenames.upstream setting, it defaults to behaving identically to pushed(). The remotenames() revset simply returns all remote branches head changesets.


Remotenames introduces a new concept to bookmarks called tracking. Its use it entirely optional. In order to start using it, pass the --track (-t) flag to the bookmarks command:

hg bookmarks mybook --track remote/@

Tracking sets up several default behaviors:

  • When pushing, if the current bookmark tracks a remote bookmark, the push destination will default to the tracked path and bookmark. For example, if the mybook local bookmark is current and is tracking remote/@, then calling hg push with be equivalent to calling hg push remote -r mybook --to @. This gives a default peer and default name to push to. We hope this will optimize many workflows.
  • When rebasing (if the rebase extension is enabled), hg rebase with no arguments changes behavior as well. When the current bookmark is tracking another name, hg rebase will default to rebasing on top of the tracked name. For example, if mybook is the current bookmark, hg rebase with no arguments will be the equivalent of: hg rebase -b mybook -d remote/@. Note that in this usage, the tracked name does not have to be a remote bookmark: bookmarks can track other local bookmarks, and rebase will use that as a default rebase destination.
  • When pulling with the --rebase flag from an active bookmark that's tracking a remote bookmark, local changes are rebased on that remote bookmark.
  • Finally, tracking allows a distance calculation, so you know how far ahead and behind a given bookmark is from the name it is tracking. In the diagram in the Introduction above, for example, the feature bookmark is 2 behind and 2 ahead of the @ bookmark. Distance is covered in more detail in the next section.

To see a listing of what a bookmark is tracking, use hg bookmarks -v.


For actions that create commits or update to another changeset (commit, rebase, histedit, update, etc.), the distance to the default path is written in .hg/remotedistance. The format of this file is 'SIGN NUMBER', e.g. '+ 10' or '- 7'. This is handy for use in your shell prompt.

For example, the following is in my bash prompt:

remote="$(less $repo_dir/.hg/remotedistance 2>/dev/null)"
[[ ${remote:0:1} == "-" ]] && sign="⇣"
distance="$(echo $remote | cut -d ' ' -f2)"
[[ "$distance" != "" && "$distance" != "0" ]] && remote=" $distance$sign"

This tells me how many commits I'm ahead or behind in my prompt.

By default, the distance is caclulated after each write operation and cached for quick lookup. However, in repositories with high commit rates, the distance calculation can take a long time, so you can disable it using the following configuration bits:

[remotenames] cachedistance = False

It is also possible to disable all distance calculation (even those in tracked bookmarks) with the calculatedistance knob:

[remotenames] calculatedistance = False


The authors appreciate feedback and would be glad to hear from you. Please ask questions or provide feedback on the Mercurial mailing lists. We actively follow these lists and are excited to have people try this extension and let us know what they think.

Thank you for trying out remotenames!