mirror of
https://github.com/facebook/sapling.git
synced 2024-10-12 01:39:21 +03:00
210 lines
7.0 KiB
ReStructuredText
210 lines
7.0 KiB
ReStructuredText
.. -*-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
|