[PATCH 1 of 5] transplant: clarify what --branch do - it has nothing to do with branches

[Mads Kiilerich]

# HG changeset patch
# User Mads Kiilerich <madski at unity3d.com>
# Date 1366132718 -7200
#      Tue Apr 16 19:18:38 2013 +0200
# Node ID 94d590a8fb68fc21a8493bc19c6775e9aa3136b5
# Parent  12a3474c163430293c99fd21b7745dfb8f9bc04e
transplant: clarify what --branch do - it has nothing to do with branches

--branch specifies heads and has nothing to do with named branches, and it only
deals with topological branches to the same extent as all other DAG operations
do.

diff --git a/hgext/transplant.py b/hgext/transplant.py
--- a/hgext/transplant.py
+++ b/hgext/transplant.py
@@ -493,9 +493,8 @@
 
 @command('transplant',
     [('s', 'source', '', _('pull patches from REPO'), _('REPO')),
-    ('b', 'branch', [],
-     _('pull patches from branch BRANCH'), _('BRANCH')),
-    ('a', 'all', None, _('pull all changesets up to BRANCH')),
+    ('b', 'branch', [], _('use this source changeset as head'), _('REV')),
+    ('a', 'all', None, _('pull all changesets up to the --branch revisions')),
     ('p', 'prune', [], _('skip over REV'), _('REV')),
     ('m', 'merge', [], _('merge at REV'), _('REV')),
     ('', 'parent', '',
@@ -527,15 +526,18 @@
     $1 and the patch as $2.
 
     If --source/-s is specified, selects changesets from the named
-    repository. If --branch/-b is specified, selects changesets from
-    the branch holding the named revision, up to that revision. If
-    --all/-a is specified, all changesets on the branch will be
-    transplanted, otherwise you will be prompted to select the
-    changesets you want.
+    repository.
+    If --branch/-b is specified, these revisions will be used as
+    heads when deciding which changsets to transplant, just as if only
+    these revisions had been pulled.
+    If --all/-a is specified, all the revisions up to the heads specified
+    with --branch will be transplanted.
 
-    :hg:`transplant --branch REV --all` will transplant the
-    selected branch (up to the named revision) onto your current
-    working directory.
+    Example:
+
+    - transplant all changes up to REV on top of your current revision::
+
+        hg transplant --branch REV --all
 
     You can optionally mark selected transplanted changesets as merge
     changesets. You will not be prompted to transplant any ancestors
@@ -557,13 +559,16 @@
             if match(node):
                 yield node
 
-    def transplantwalk(repo, root, branches, match=util.always):
-        if not branches:
-            branches = repo.heads()
+    def transplantwalk(repo, dest, heads, match=util.always):
+        '''Yield all nodes that are ancestors of a head but not ancestors
+        of dest.
+        If no heads are specified, the heads of repo will be used.'''
+        if not heads:
+            heads = repo.heads()
         ancestors = []
-        for branch in branches:
-            ancestors.append(repo.changelog.ancestor(root, branch))
-        for node in repo.changelog.nodesbetween(ancestors, branches)[0]:
+        for head in heads:
+            ancestors.append(repo.changelog.ancestor(dest, head))
+        for node in repo.changelog.nodesbetween(ancestors, heads)[0]:
             if match(node):
                 yield node
 
@@ -575,7 +580,7 @@
             return
         if not (opts.get('source') or revs or
                 opts.get('merge') or opts.get('branch')):
-            raise util.Abort(_('no source URL, branch tag or revision '
+            raise util.Abort(_('no source URL, branch revision or revision '
                                'list provided'))
         if opts.get('all'):
             if not opts.get('branch'):
@@ -608,12 +613,12 @@
     sourcerepo = opts.get('source')
     if sourcerepo:
         peer = hg.peer(repo, opts, ui.expandpath(sourcerepo))
-        branches = map(peer.lookup, opts.get('branch', ()))
+        heads = map(peer.lookup, opts.get('branch', ()))
         source, csets, cleanupfn = bundlerepo.getremotechanges(ui, repo, peer,
-                                    onlyheads=branches, force=True)
+                                    onlyheads=heads, force=True)
     else:
         source = repo
-        branches = map(source.lookup, opts.get('branch', ()))
+        heads = map(source.lookup, opts.get('branch', ()))
         cleanupfn = None
 
     try:
@@ -637,7 +642,7 @@
             if source != repo:
                 alltransplants = incwalk(source, csets, match=matchfn)
             else:
-                alltransplants = transplantwalk(source, p1, branches,
+                alltransplants = transplantwalk(source, p1, heads,
                                                 match=matchfn)
             if opts.get('all'):
                 revs = alltransplants