[MERGE/RFC] Checkouts help topic.

[James Westby]

Hi Aaron, thanks for some good comments. Most I will change and then
resubmit.

On (01/02/07 22:33), Aaron Bentley wrote:
> James Westby wrote:
> 
> Some mention of using them with treeless repositories would be a good idea.
> 

As in bzr checkout . for when you forgot trees, or minimising working
trees by only checking out ones that you want? I think you mean the
latter. I was thinking of including the former in the repositories help
topic.

> > +A checkout is created with the bzr checkout command (see "help checkout").
> > +You pass it a reference to another branch, and it will create a local branch
> > +for you that still contains a reference to the branch you created the
> > +checkout from (the master branch).
> 
> I don't think it's helpful to speak of "checkouts" as being "branches".
> 
> The key point is that it's a tree, and when you commit to that tree, the
> commit goes into the master branch.  That is the most important
> behavior, and one that is common to both kinds of checkouts.
> 
> The fact that a heavy branch contains a local copy of remote data is
> more important than the fact that the local copy is represented as a branch.

Yes, that sounds fair. I think it still needs to be clear it is a branch
lower down, but shouldn't start with that.

I was writing this with the particular user's issue in mind, so I might
have made it too specific, and missed some other checkout uses or
issues.

> You can also branch from a lightweight checkout.  It too contains a
> full-featured branch; "a branch reference" to the master branch.

Thanks, I did wonder this, but forgot to explicity ask in the reiew
request. Thanks for picking up on it.

> > +It is also possible to create a "lightweight" checkout by passing the
> > +--lightweight flag to checkout. A lightweight checkout is even closer to an
> > +SVN checkout in that it is not a first class branch, it mainly consists of the
> > +working tree. This means that any history operations must query the master
> > +branch, which could be slow if a network connection is involved. Also, as you
> > +don't have a local branch, then you cannot commit locally.
> 
> It would be good to also write of the advantages of lightweight checkouts:
> 
> Lightweight checkouts work best when you have fast, reliable access to
> the master branch.  So if the master is on the same disk or on a LAN, a
> heavyweight checkout will tend to be bigger and slower than a
> lightweight checkout.

...for initial creation?

I will add something that explicity gives the relative merits of each.

> > +
> > +Useful commands:
> 
> "Related commands"?  (We don't have any useless commands, do we? :-)

Ha, of course not.

Thanks,

James

-- 
  James Westby   --    GPG Key ID: B577FE13    --     http://jameswestby.net/
  seccure key - (3+)k7|M*edCX/.A:n*N!>|&7U.L#9E)Tu)T0>AM - secp256r1/nistp256