[RFC] proposed user doc for nested trees
aaron at aaronbentley.com
Tue May 12 12:55:11 BST 2009
-----BEGIN PGP SIGNED MESSAGE-----
Martin Pool wrote:
> I liked the document a lot, both as something that can eventually
> become user documentation, and as a way to clarify the conversation
> about what we are going to merge into bzr.
I think it makes a lot more sense to start with the NestedTreesDesign
document which I updated at your request, and look at user-level
documentation afterward, as a supplement to it.
> I think this document needs a bit more detail about what's happening
> behind the ui, and so does this conversation if it's to move forward
Is that detail that is missing from NestedTreesDesign?
> You cover it pretty well in some places by say what is or
> isn't stored, but I think for users to really understand this they
> need a model of what's recorded in the committed
> inventories/revisions, what's in the working tree, and what's in the
The changes to the storage are described at
> The behaviour of 'bzr branch' on containing branches isn't explained
> by itself, only in passing in 'Virtual projects'. From there we can
> infer when you branch, it brings across in the committed revisions
> references to the other branches, so we know those nested trees exist,
> and it seems that their working trees are created.
The behavior of branch is described at
> Are they branched
> from the branches in the source, or are they pulled from the same
> reference URL they originally came from? (The second seems
> problematic if you're pushing to a server, because in general we don't
> assume that the server can go and make outgoing connections on your
> What happens if you have a branch with no working tree?
There is discussion of that in NestedTreesDesign.
> the fact that the nested trees were there is still present.
> Is the
> data copied correctly in this case?
> Do they all go into the same
If the containing tree's branch is part of a shared repo, yes.
> Will running 'bzr checkout' then reconstruct all the
> nested trees? (Perhaps obviously yes.)
> One question possibly out of scope for this design: some other systems
> (like configmanager?) let you have the top level tree require creation
> of ./a and ./a/b without ./a needing to know anything about it.
This design assumes that if a contains b, then a depends on b.
> The only case I've seen for that is when people have a top-level tree
> which just does the assembly and nothing else. It can probably be
> delayed; it may be worth noting as a restriction.
I have no idea how this design could be modified later so that the
presence of b was specified by the top-level directory, not by a. If
that's an important feature, we should rethink this design now.
>> bzr branch --nested
> I think "remember this branch in the parent" is more of an operation
> in its own right than someting just done by 'bzr branch'.
I was assuming branch --nested was essentially "bzr branch http://foo &&
bzr join --nested foo".
> For example
> you might want to init a new nested tree, or you might already have an
> untracked nested branch constructed by some other means. So why not
> have 'bzr join' or 'bzr add --nested' (though the second seems now
We also have bzr join --nested. I don't consider add to be explicit enough.
> I'd like, more for the sake of this discussion though it would also
> help users, to see how this would be shown by 'bzr status'. If it
that status is recursive.
> then it should show you the changes in the nested trees,
> obviously, but it also seems to need to show that the version of the
> nested tree in the parent is not what's in that branch.
You mean, in cases where the last-revision in the nested tree has
changed without the files changing?
> Ideally we would have one consistent rule for all commands as regards
> descent into nested trees. If it's "they all recurse" that's great;
It is: http://bazaar-vcs.org/NestedTreesDesign#downwards-recursion
> Also, I think the code changes will be such that commands that aren't
> explicitly updated won't recurse; that's probably the only sane
> approach. So that means that code in bzr that's not updated will
> default to not recursing, and code in other places (like bzr-gtk or
> qbzr) won't recurse either, at first.
True. The issue is that we want to take small steps. Before we
consider this feature 'beta', we will ensure consistent behaviour of
And we can add support for additional commands incrementally.
> I think I'd rather be in the situation where they're all consistent
> (and not recursing) but some are lacking a useful option.
I would like to be consistent, but I think it's more important to decide
the correct behaviour. Once that's decided, we can figure out how to
get to a consistent implementation of that behaviour.
>> nested branch locations are not tracked over time
> I think we should say here where they are stored. As non-versioned
> data in the branch, like tags?
>> bzr nested DIR LOCATION
> So this seems to me a lot like the issue of managing the push, pull,
> etc default locations
No, it's managing the reference locations, which are the locations,
relative to the top-level branch, of the sub-branches.
> It seems like for nested branches you want to control the
> push, pull location for them too.
Yes, but only in the normal way.
> This section is actually raising a bit of a conceptual question for
> me: are you saying that the nested branches have their own tip
> pointer, or that they're really checkouts of branches held somewhere
The working trees are checkouts, the branches are real branches:
>> To delete the location of a nested branch: bzr nested --delete DIR
> The text seems to imply that does not delete the directory, just
> forgets the location of its branch. Are you then left with a checkout
> with no branch, in which you can't do anything much until you
> essentially rebind it?
> I'm most concerned that this will come in when people have related but
> distinct branches that share file ids, eg if they both started by
> branching from a common template. Or you might plausibly have
> libfoo1.1 and libfoo2.0 that share history.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org
-----END PGP SIGNATURE-----
More information about the bazaar