Merge lp://qastaging/~jelmer/bzr/fix-for-105432 into lp://qastaging/bzr

> This command should be easier to find than "bzr checkout", which
> confusingly can both create checkouts and working trees.
> [...]
> Perhaps we should also deprecate the existing behaviour in "bzr
> checkout ." and ask people to use "bzr create-tree" instead?

I object to this in principle, as muddying conceptual waters that are
already squirreled up enough. Creating a working tree for a branch
_IS_ what checkout is for.

Adding another different command just because sometimes it's colocated
and sometimes it's not is a step away from clarity and deeper into a
morass of special cases to memorize that we already have enough
training problems with...

On 17 December 2011 05:46, Matthew Fuller <email address hidden> wrote:
>  Creating a working tree for a branch _IS_ what checkout is for.

There are two different operation modes. When the source and
destination are the same, this does what create-tree will do:

 * the bzrdir must exist
 * if it already has a working tree, do nothing
 * otherwise, create a working tree

if they are different, call branch.create_checkout:

 * makes a new bzrdir
 * makes a working tree in it, with either a local bound branch or a
reference to another branch

Going towards commands that have a simple mapping to the underlying
operations should make things clearer: it is an improvement the
definition of this command has fewer special cases.

But, perhaps the other case of creating a wt separate from the branch
ought to be accommodated here somewhere.

--
Martin

> There are two different operation modes.
[...]

But there aren't, there's only one; create a working tree for a
branch. There may be different details that happen under the covers
for various cases, but the user intention is (should be) the same.

This is why we have training issues around it :)

> Going towards commands that have a simple mapping to the underlying
> operations should make things clearer: it is an improvement the
> definition of this command has fewer special cases.

I think it's quite the opposite; going toward commands that have a
simple mapping to the _overarching_ operations makes things clearer
here.

Insofar as the differences in underlying implementation details leak
through and cause confusion and seemingly different command
definitions, _those_ are bugs that need to be fixed. Using them as
the justification for splitting user-level commands up is going in
exactly the wrong direction, IMO.

> But, perhaps the other case of creating a wt separate from the
> branch ought to be accommodated here somewhere.

From a user level, there is (should be) no 'other case'. One of the
great strengths of bzr is exactly the clean(ish) separation of
concerns among repo/branch/wt, and the ability to arrange them as
appropriate locally. That opens up enough possibility for confusion;
creating whole different commands for "create working tree" based on
where it is relative to the other pieces just it worse.

So what are we going to do here?

<https://bugs.launchpad.net/bzr/+bug/105432> has some good background. I think generally, arguments that we ought to add a new name or a new alias because people would look for it under that name, are not very convincing: we can do something within the help system or documnetation that will be cheaper. However, here:

 * it is worth having a clear opposite of remove-tree
 * with this landed, 'bzr checkout' can lose its no-argument default to making a tree in the enclosing branch, and be only for making a bzrdir and tree

and, fwiw, jam, james_w and abentley are in favour of it in that bug.

[fix] If this patch proceeds, the new command ought to be mentioned in whatsnew and in the user guide. It is easier and more reliable to update those docs when the feature is added, not later.

On the whole I would merge it but we can try to get more consensus first.

> One of the great strengths of bzr is exactly the clean(ish) separation of concerns among repo/branch/wt, and the ability to arrange them as appropriate locally. That opens up enough possibility for confusion; creating whole different commands for "create working tree" based on where it is relative to the other pieces just it worse.

I agree that's a strength; can you explain more why adding this would harm it?