[RFC] proposed user doc for nested trees

[Aaron Bentley]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Martin Pool wrote:
>> by-value nesting is available now and works now, either using bzr join
>> or the merge-into plugin.  I realize that you're not suggesting we
>> disable by-value nesting.  We would simply stop calling it nesting.
> 
> Can I check how these two are currently defined:

I'm using the definitions from UBZ.  They are the same as "copy by
value" and "copy by reference" in programming languages.

> by-reference nesting: the containing tree holds basically the branch
> URL and revision to be checked out under a subdirectory.
> 
> by-value nesting: the containing tree directly contains all the files
> from the nested tree as if they'd been added, but pulling or merging
> from branches related to the nested tree will still work?

Copy-by-value means that the two trees become a single tree with the
history of both.  This is implemented by the join command and the
merge-into plugin.

It is not "as if they'd been added"; they *have* been added.

> Or is it just the difference between whether the revision of the
> nested tree is updated on every containing tree commit or not?

No.

>>> If I get permission to change checkouts as Mark has requested, all
>>> checkouts will be lightweight and heavyweight checkouts will be created
>>> via branch --bind, so "nested branch" would not be ambiguous/misleading
>>> as it could be now. See http://bazaar-vcs.org/DraftSpecs/SimpleCheckouts.
>> I still disagree.  There should be no branches at all in the working
>> tree, so they won't be nested.
> 
> What do you mean?  That in the SimpleCheckouts spec the branch is not
> colocated with the working tree?

I mean that subtrees will be lightweight checkouts of subbranches:
http://bazaar-vcs.org/NestedTreesDesign#sub-branches

Aaron
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org

iEYEARECAAYFAkoJZe4ACgkQ0F+nu1YWqI1MFACfattbrvqJ+LAxH4KoOAAqpNzC
+1oAn0f8L46Qnhb0dtkm+2u1GNDrwopY
=TSv/
-----END PGP SIGNATURE-----