There are two main ways to organize branches in Mercurial: `named
-branches`_ and bookmarks. Bookmarks are used for short-term feature or
+branches`_ and bookmarks. Bookmarks are used for short-term feature or
topic branches whereas named branches are used for long-term branches.
Named branches work well in a setting where you want to track
the context in which each changeset was made; the branch name is
embedded in the changeset and you can refer to it years later. Because
Renaming and Deleting a Bookmark
-The distinguishing feature of bookmarks compared to `named branches`_
+The distinguishing feature of bookmarks compared to `named branches`_
is that they exist *outside* of the history. Here, "history" means the
immutable changesets that cannot be changed without changing their
changeset IDs. Bookmarks are not stored in the changesets and they are
not part of the computation of changeset IDs. They can therefore be
deleted and renamed at will.
Imagine that Alice adds a new bookmark:
1 files updated, 0 files merged, 1 files removed, 0 files unresolved
$ ## snap-tortoisehg "$DSTDIR/alice-before-merge.png"
-In the update command, Alice used a `revision set`_ to select the
+In the update command, Alice used a `revision set`_ to select the
changeset that is a head with no bookmark. She can see in
TortoiseHg that she ended up at the correct changeset:
+.. __: http://www.selenic.com/mercurial/hg.1.html#revsets
.. image:: alice-before-merge.png
3. Publish your bookmark to the central repository and pull the others'
branches into your own repository.
-4. See the `revision set`_ documentation and try a query like `hg
+4. See the `revision set`_ documentation and try a query like `hg
log -r "ancestors(NAME) - ancestors(.)"` to see changesets on the
branch ``NAME`` that have not yet been merged into your current
revision. Revision sets also work in TortoiseHg.
+ .. __: http://www.selenic.com/mercurial/hg.1.html#revsets
5. Update to one of the other branches and make a commit. Push this
back to the server and experiment with managing divergent
-6. Enable the `rebase extension`_ and try rebasing a feature branch on
- top of the main line of development. The bookmarks should follow
+6. Enable the `rebase extension`__ and try rebasing a feature branch
+ on top of the main line of development. The bookmarks should follow
+ .. __: http://mercurial.selenic.com/wiki/RebaseExtension
few guides out there that now contain outdated information. You can
compare the publication date of a guide with the table above to see which
features the guide cannot possibly know about.
-.. _named branches: ../tasks/
-.. _revision set: http://www.selenic.com/mercurial/hg.1.html#revsets
-.. _rebase extension: http://mercurial.selenic.com/wiki/RebaseExtension