"bzr send -r" needs help text

Trivial to fix but important.

<poolie> abentley, so what is the meaning of -r for bzr send now?
<abentley> It controls the patch preview, and it controls how the merge is applied, but it does not control which revisions are included in the bundle.
<poolie> so the merge is done as if you'd typed merge -r XXXX
<ubotu> New bug: #150427 in bzr ""bzr send -r" needs help text" [Undecided,New] https://launchpad.net/bugs/150427
<abentley> poolie: Right.
<abentley> Or -r X..Y, for that matter.

Just to clarify, I'm pretty sure it does effect the target revision (the one to be merged), and thus what revisions will be included in the bundle. What it doesn't change is what *ancestral* revisions to include. That is chosen based on what is not present in the 'submit' branch.

So doing:

  bzr branch upstream local
  cd local
  hack, commit revision 10, 11, 12

Doing:

  bzr send

Will send a merge directive containing revisions 10, 11, 12, and doing "bzr merge XXX" will be as if you did "bzr merge local"

Doing:

  bzr send -r 11

Will send a MD containing revisions 10 and 11, and doing "bzr merge XXX" will be equivalent to "bzr merge -r 11 local"

Doing:

  bzr send -r 11..12

Will send an MD containing revisions 10, 11, and 12, but showing a patch preview of only "bzr diff -r 11..12", and doing "bzr merge XXX" is equivalent to "bzr merge -r 11..12 local" (cherrypick the last revision changes).

Note that at merge time, it is not possible to select what revisions to merge. So you can't do "bzr merge -r 11 XXX" even though all merge directives contain that revision.

At the moment, you could do "bzr merge XXX; bzr revert; bzr merge -r revid:REV ." Where REV is the id of rev 11. Since that revision will be copied to the local repository as part of merging the MD.

Paul Moore also suggests:

"""
The submit branch is the branch to which the bundle is intended to be
applied. It is needed if an explicit revision range is given, so that
the command can check that it has the base revision for the bundle
already present (otherwise, the bundle will not apply).
"""

And see the recent thread "Cannot merge bundles created without referencing another branch"