Note:
This page is primarily intended for developers of Mercurial.
Bookmarks Plan
![/!\](/moin-static/modernized/img/alert.png "/!\"){kind=small}
This is a DRAFT for discussion, and does not represent any firm decisions on future behavior.
Original draft by KevinBullock.
A plan to smooth out the usage of bookmarks as short-lived branches (a.k.a. feature branches). This covers several facets of bookmarks that have been discussed recently (June 2012) on the mailing list:
- Providing a default-update-on-clone bookmark (the '@' bookmark)
- Introducing bookmarks (particularly as experimental branches) sanely into a workflow where they're not being used
- When to sync bookmarks automatically
Contents
1. Discussions
For context and other proposals that have been made on the -devel list and elsewhere, see the following:
2. Removing current/active dichotomy
As of 2.4, a bookmark is 'current' if it's the one listed in .hg/bookmarks.current, and 'active' if it is both current and the working directory parent. This creates problems like bug 3682, and is tracked separately as bug 3683.
The resolution implemented in 2.5 is this:
Keep the 'current' bookmark 'active' even if it gets moved by a pull, and make hg update update to the active bookmark. An explicit hg update REV where REV is not the current bookmark would deactivate the current bookmark (remove .hg/bookmarks.current). 
hg summary needs to be updated to indicate when an update would move to the active-but-moved bookmark. See http://markmail.org/message/eyben3uq3snfz7on .
The code should also be cleaned up so that method and variable names reflect the new semantics.
3. Introducing Bookmarks Into Your Workflow
mpm posed the following problem: Alice and Bob are working on a branch. Alice updates to the branch head and commits, then starts some experimental work. She commits and bookmarks her work as alice-work. When Bob pulls and updates, he should move forward one commit. Instead he gets everything in alice-work, which is now the branch head.
To solve this, I propose:
Adding the first bookmark to any named branch also creates an implicit default bookmark on that named branch, with the same name as the branch[?]. This implicit per-named-branch default is created regardless of whether the bookmark was added by the bookmark command, push, pull, or clone.
The implicit bookmark for the current branch is treated as active if no other bookmark is active.
No implicit bookmark is created on any named-branch without other bookmarks.
4. Command Behavior with Bookmarks
4.1. bookmark
Make hg bookmark -f deactivate the current bookmark when moving it.
Make hg bookmark MARK activate MARK if it points to a working dir parent, without requiring --force.
Make hg bookmark MARK move an existing MARK forward to a descendant, without requiring --force.
4.2. clone
Clone all bookmarks.
Update to '@' if it exists, otherwise fall back to 'default' or 'tip'.
4.3. pull
Pull all bookmarks.
If you don't want to expose the bookmarks, then mark the changesets secret; this leads us to:
4.4. commit
Add an option that commits the working directory as secret and creates a bookmark (http://markmail.org/message/vx7ub3pojxlccgdx).
4.5. push
hg push -B BOOKMARK pushes only the changesets through BOOKMARK. I.e., it is equivalent to hg push -B BOOKMARK -r BOOKMARK.
Warn (with hint) when pushing changesets that are bookmarked without pushing the bookmarks (suggested by marmoute: http://markmail.org/message/pxemyessq6ek7ynw).
The above proposed behavior is a compromise between local-only bookmarks and topic-branch bookmarks. Those who are used to topic branches in Git are also used to naming them explicitly to push them. And to quote: "Yes, push and pull are definitely asymmetrical. This should be no surprise to anyone who's used a rope." (http://markmail.org/message/mlxueu2lnxi7ewq5)
4.6. update
Update to a bookmark named explicitly on the command line makes that bookmark active.
Bare update moves the active bookmark forward.
- Bare update with no active bookmark updates to the implicit branch-default bookmark if it exists (see above).
- What if it doesn't exist, i.e., how/when to add the implicit bookmark to old repos?
4.7. merge
Don't advance bookmark from p2 of a merge (this was issue1877).
Automatically resolve divergent bookmarks: when on a bookmarked branch, merging with a branch with a divergent copy of the bookmark deletes the copy on the other branch.
Currently, this means that if you're on the branch with the divergent copy (foo@remote), and merge with the original, the divergent bookmark (the one with '@' in the name) gets kept. This is probably wrong.
4.8. rebase
Automatically resolve divergent bookmarks: when rebasing a local bookmark onto a branch with a divergent copy of that bookmark, delete the divergent copy (issue3685).