Differences between revisions 1 and 11 (spanning 10 versions)
Revision 1 as of 2012-06-08 19:37:46
Size: 3726
Editor: KevinBullock
Comment: Create first draft
Revision 11 as of 2012-11-01 19:06:59
Size: 4922
Editor: KevinBullock
Comment: link mpm's name to his page
Deletions are marked like this. Additions are marked like this.
Line 2: Line 2:
<<Include(A:dev)>>
Line 4: Line 5:

/!\ This page is intended for developers.
Line 24: Line 23:
 * http://markmail.org/message/5kn5joi7t5q2euvr
Line 29: Line 29:


== 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 [[http://bz.selenic.com/show_bug.cgi?id=3682|bug 3682]], and is tracked separately as [[http://bz.selenic.com/show_bug.cgi?id=3683|bug 3683]].

There are two current proposals to resolve this:

1. Invoke the divergent bookmarks mechanism if the active bookmark would be moved by a pull (see http://markmail.org/message/336pw3v4wh5dtgom). Proposed by KevinBullock. There is currently no easy way to resolve this divergence, since `hg merge` will refuse to merge with an ancestor. If merge were made to resolve this, we would suddenly have fast-forward "merges", which we've resisted in the past as hard for users to grasp.

2. Keep the 'current' bookmark 'active' even if it gets moved by a pull, and make `hg update` update to the active bookmark. Proposed by [[mpm]].
Line 46: Line 57:
=== bookmark ===

* Make `hg bookmark -f` deactivate the current bookmark when moving it.
Line 49: Line 64:
 * Update to '@' if it exists, otherwise fall back to 'default' or 'tip'.  * Update to '@' if it exists, otherwise fall back to 'default' or 'tip'. (./)
Line 53: Line 68:
 * Pull all bookmarks.  * Pull all bookmarks. (./)
Line 63: Line 78:
 * `hg push -r BOOKMARK` should automatically sync the bookmark too, without having to specify `-B`.  * `hg push -B BOOKMARK` should push only the changesets through BOOKMARK. I.e., it should be equivalent to `hg push -B BOOKMARK -r BOOKMARK`. (./)
Line 68: Line 83:
This 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) 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)
Line 75: Line 90:
   * What if it doesn't exist, i.e., how/when to add the implicit bookmark to
    
old repos?
   * What if it doesn't exist, i.e., how/when to add the implicit bookmark to old repos?

Note:

This page is primarily intended for developers of Mercurial.

Bookmarks Plan

/!\ 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

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.

There are two current proposals to resolve this:

1. Invoke the divergent bookmarks mechanism if the active bookmark would be moved by a pull (see http://markmail.org/message/336pw3v4wh5dtgom). Proposed by KevinBullock. There is currently no easy way to resolve this divergence, since hg merge will refuse to merge with an ancestor. If merge were made to resolve this, we would suddenly have fast-forward "merges", which we've resisted in the past as hard for users to grasp.

2. Keep the 'current' bookmark 'active' even if it gets moved by a pull, and make hg update update to the active bookmark. Proposed by mpm.

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.

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

4.5. push

  • hg push -B BOOKMARK should push only the changesets through BOOKMARK. I.e., it should be 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).

Discussion: It should be possible to push a bookmark and all the changesets leading up to it in one command. Right now, hg push -B BOOKMARK pushes _all changesets_, and then the given bookmark, which is too much.

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?


CategoryDeveloper

BookmarksPlan (last edited 2015-06-12 10:48:17 by Pierre-YvesDavid)