.. -*-restructuredtext-*-

===========
remotenames
===========

------------
Introduction
------------

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.

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.

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

  [paths]
  default = http://smf.io/hgremotenames
  smf = http://smf.io/hgremotenames

Since those two paths are equal, the non-default name is chosen.

Remote names are discovered by sending a single extra request to the Mercurial
server after the 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 introduce in 3.3.

------------
Installation
------------

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

  [extensions]
  remotenames = /path/to/hgremotenames/remotenames.py

----------------
Behavior Changes
----------------

Since this extensions keeps track of the remote bookmarks, we no longer pull
them by default (similar with clone). Therefore, pulling from a remote server
will no longer pollute your bookmarks.

Expect changes.

The commands ``bookmarks``, ``branches``, and ``log`` all gain a ``--remote``
flag to display remote names. This will also unhide obsolete changesets.

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 experimental-feature
  <hack, hack, hack>
  hg push
  pushing to foo
  searching for changes
  abort: push creates new anonymous head without the bookmark: 'experimental-feature'
  (use 'hg push -B experimental-feature' to create a new remote bookmark)

---------
Templates
---------

Remotenames adds the following new template keywords: ``remotebranches``,
``remotebookmarks``, and ``remotenames`` which is the combination of the first
two. For example, the diagram above uses the template ``({remotebranches})
[{remotebookmarks}]``. You could drop the ``remotebranches`` keyword if that's
your fancy.

Alternatively, you could use ``remotenames`` to include both namespaces. If you
set the configurable option ``suppressbranches``::

  [remotenames]
  suppressbranches = True

Then ``remotenames`` will only display the branch name if there is no bookmark
present.

-----
Alias
-----

Experimental. Setting ``alias.default = True`` will drop the turn
``smf/default`` into just ``smf``.

-------
Revsets
-------

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.

--------
Distance
--------

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)"
  sign="⇡"
  [[ ${remote:0:1} == "-" ]] && sign="⇣"
  distance="$(echo $remote | cut -d ' ' -f2)"
  remote=""
  [[ "$distance" != "" && "$distance" != "0" ]] && remote=" $distance$sign"

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

-------
Pushing
-------

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

Finally, there is a new config option to enforece using ``--to`` if that is
apropriate in your chosen workflow. To enable it, set the option ``forceto``::

  [remotenames]
  forceto = True

-------------------
Cloning and Pulling
-------------------

As mentioned above under the ``Behavior Changes`` section, pulls by default
will not sync 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::

  [remotenames]
  syncbookmarks = True