Patchwork [1,of,3,STABLE] help: update help on bookmarks push/pull

login
register
mail settings
Submitter Kevin Bullock
Date June 10, 2014, 1:59 a.m.
Message ID <d42fb8228f53f963bab6.1402365553@billings.hsd1.mn.comcast.net>
Download mbox | patch
Permalink /patch/4959/
State Superseded
Headers show

Comments

Kevin Bullock - June 10, 2014, 1:59 a.m.
# HG changeset patch
# User Kevin Bullock <kbullock@ringworld.org>
# Date 1402362637 18000
#      Mon Jun 09 20:10:37 2014 -0500
# Branch stable
# Node ID d42fb8228f53f963bab6b011c3ed9624a14c62f8
# Parent  dedb68a9532cafde83ccafee1ef2c1e6b02ac189
help: update help on bookmarks push/pull
David Soria Parra - June 12, 2014, 4:03 a.m.
Kevin Bullock <kbullock+mercurial@ringworld.org> writes:

>  Bookmark
> -    Bookmarks are pointers to certain commits that move when
> -    committing. They are similar to tags in that it is possible to use
> -    bookmark names in all places where Mercurial expects a changeset
> -    ID, e.g., with :hg:`update`. Unlike tags, bookmarks move along
> -    when you make a commit.
> +    Bookmarks are lightweight pointers to commits. They are similar to
> +    tags in that it is possible to use bookmark names in all places
> +    where Mercurial expects a changeset ID, e.g., with
> +    :hg:`update`. Unlike tags, bookmarks move along when you make a
> +    commit.
I actually think the tag comparision should be removed as it is
confusing. It should say: "Bookmark names can used in all places where
Mercurial expects a changset". The current form of LIKE X except for
a,b,c also leads to people expecting behaviours which might not exist.

The rest of the patch is really nice. Thanks for working on that.

> -
Matt Mackall - June 25, 2014, 12:54 a.m.
On Wed, 2014-06-11 at 23:10 -0500, Kevin Bullock wrote:
> On Jun 11, 2014, at 11:03 PM, David Soria Parra <davidsp@fb.com> wrote:
> 
> > Kevin Bullock <kbullock+mercurial@ringworld.org> writes:
> > 
> >> Bookmark
> >> -    Bookmarks are pointers to certain commits that move when
> >> -    committing. They are similar to tags in that it is possible to use
> >> -    bookmark names in all places where Mercurial expects a changeset
> >> -    ID, e.g., with :hg:`update`. Unlike tags, bookmarks move along
> >> -    when you make a commit.
> >> +    Bookmarks are lightweight pointers to commits. They are similar to
> >> +    tags in that it is possible to use bookmark names in all places
> >> +    where Mercurial expects a changeset ID, e.g., with
> >> +    :hg:`update`. Unlike tags, bookmarks move along when you make a
> >> +    commit.
> > I actually think the tag comparision should be removed as it is
> > confusing. It should say: "Bookmark names can used in all places where
> > Mercurial expects a changset". The current form of LIKE X except for
> > a,b,c also leads to people expecting behaviours which might not exist.
> 
> I agree, and I thought about including that change. At this point I could just as easily do a follow-up patch.
> 
> I'll wait a day or two to see if anyone wants to bikeshed further, then crew these.

Doh. With my large backlog, I wasn't aware this was on the list, and
more or less rewrote the help last week by putting it on Titanpad for
some collaborative editing:

http://www.selenic.com/hg/rev/0c6cdbb697d9

Feel free to bikeshed my version by follow-up patch.

Patch

diff --git a/mercurial/commands.py b/mercurial/commands.py
--- a/mercurial/commands.py
+++ b/mercurial/commands.py
@@ -797,10 +797,9 @@  def bisect(ui, repo, rev=None, extra=Non
 def bookmark(ui, repo, *names, **opts):
     '''track a line of development with movable markers
 
-    Bookmarks are pointers to certain commits that move when committing.
-    Bookmarks are local. They can be renamed, copied and deleted. It is
-    possible to use :hg:`merge NAME` to merge from a given bookmark, and
-    :hg:`update NAME` to update to a given bookmark.
+    Bookmarks are lightweight pointers to commits. They can be renamed, copied
+    and deleted. It is possible to use :hg:`merge NAME` to merge from a given
+    bookmark, and :hg:`update NAME` to update to a given bookmark.
 
     You can use :hg:`bookmark NAME` to set a bookmark on the working
     directory's parent revision with the given name. If you specify
diff --git a/mercurial/help/glossary.txt b/mercurial/help/glossary.txt
--- a/mercurial/help/glossary.txt
+++ b/mercurial/help/glossary.txt
@@ -6,16 +6,17 @@  Ancestor
     ancestor. See also: 'Descendant'.
 
 Bookmark
-    Bookmarks are pointers to certain commits that move when
-    committing. They are similar to tags in that it is possible to use
-    bookmark names in all places where Mercurial expects a changeset
-    ID, e.g., with :hg:`update`. Unlike tags, bookmarks move along
-    when you make a commit.
+    Bookmarks are lightweight pointers to commits. They are similar to
+    tags in that it is possible to use bookmark names in all places
+    where Mercurial expects a changeset ID, e.g., with
+    :hg:`update`. Unlike tags, bookmarks move along when you make a
+    commit.
 
-    Bookmarks can be renamed, copied and deleted. Bookmarks are local,
-    unless they are explicitly pushed or pulled between repositories.
-    Pushing and pulling bookmarks allow you to collaborate with others
-    on a branch without creating a named branch.
+    Bookmarks can be renamed, copied and deleted. Bookmarks are cloned
+    and pulled along with the changes they point to. They are not pushed
+    to remote repositories by default, but can be explicitly shared (see
+    :hg:`help update`). Pushing and pulling bookmarks allow you to
+    collaborate with others on a branch without creating a named branch.
 
 Branch
     (Noun) A child changeset that has been created from a parent that