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.

hgext/transplant.py

@@ -493,9 +493,8 b' def browserevs(ui, repo, nodes, opts):'
 
 @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 b' def transplant(ui, repo, *revs, **opts):'
     $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 b' def transplant(ui, repo, *revs, **opts):'
             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 b' def transplant(ui, repo, *revs, **opts):'
             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 b' def transplant(ui, repo, *revs, **opts):'
     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 b' def transplant(ui, repo, *revs, **opts):'
             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