[MERGE][Bug #183559] Add a -r option to bzr switch

[Ian Clatworthy]

Daniel Watkins wrote:
> The attached fixes a test which I'd somehow missed previously, and
> starts using the helper function that was just merged.

The code for this looks fine. At the risk of making perfect the
enemy of good, I'd like to see some additional tests though
because I'd like to be more confident that this won't break in
the wild:

* expand the switch tests to be more complex, e.g. test switching
  back and forth between revisions where a directory with contents
  has been removed vs is present.

* a blackbox test checking the error message when neither a
  location nor a revision is given

* add a test checking behaviour of switch -r on a lightweight
  checkout with uncommitted changes. My expectation is that this
  should fail unless --force is given. Sound right?

bb:resubmit

A minor doc tweak requested too ...

> -def switch(control_dir, to_branch, force=False):
> +def switch(control_dir, to_branch, force=False, revision_id=None):
>      """Switch the branch associated with a checkout.
>  

This is a public function so the docstring needs to have
revision_id explained as a parameter.

Also, do you think the switch help needs any improvements to
explain this option? (Just listing the option is probably
enough but I thought I'd ask.)

Ian C.