mirror of
https://github.com/facebook/sapling.git
synced 2024-10-12 01:39:21 +03:00
A Scalable, User-Friendly Source Control System.
tests | ||
.hgignore | ||
Makefile | ||
README | ||
remotenames.py | ||
setup.py |
.. -*-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