[MERGE/RFC] Checkouts help topic.

[Aaron Bentley]

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

James Westby wrote:
> -    All subsequent commits will be local.
> +    All subsequent commits will be local. This turns a heavy checkout in to
> +    a normal branch.

"into", not "in to" (compare "Writing my report turned me into a nervous
wreck" with "I handed my report in to the professor")

> +_checkouts = \
> +"""Checkouts
> +
> +Checkouts are a way of working with Bazaar that can be quite simple, but also
> +very useful, as they allow you to ignore some of the features of distributed
> +version control that Bazaar has until you need them. Using them can give you
> +a workflow that is very similar to SVN, but still allow others working on
> +the project to use another workflow, allow you flexibility in your own
> +workflow, and still provide some of the improvements of Bazaar over SVN to
> +you.

Some mention of using them with treeless repositories would be a good idea.

> +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.

> Then if you commit any changes to your local
> +branch those commits will be made on the other branch first. This creates an
> +instant mirror of your work, or facilitates lockstep development, where each
> +developer is working together, continuously integrating the changes of others.
> +
> +However the checkout is still a first class branch in Bazaar terms, so that
> +you have the full history locally, and can branch from it, for example to
> +work on a feature branch.

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

> +As you have a first class branch you can also commit locally if you want,
> +for instance due to the temporary loss af a network connection. Use the
> +--local option to commit to do this.
> +
> +If you are using a checkout from a shared branch you will periodically want to
> +pull in all the changes made by others. This is done using the "update"
> +command. The changes need to be pulled before any commit, but Bazaar will tell

Perhaps "...need to be applied before any (non-local) commit..."?

> +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.

> +Obviously to commit on a checkout you need to be able to write to the master
> +branch. This means that there must be a writeable transport in between

We should try to avoid "transport".  "That means the branch must be
available on a writable protocol..." ?

> +You can change the master of a checkout by using the "bind" command (see "help
> +bind"). This will change the location that the commits are sent to. The bind
> +command can also be used to turn a branch in to a heavy checkout. If you

"into" again

> +would like to convert your heavy checkout to a normal branch so that every
> +commit is local you can use the "unbind" command.

comma needed: "...commit is local, you can..."

> +
> +Useful commands:

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

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

iD8DBQFFwrEX0F+nu1YWqI0RAhTwAJ45HD5bjBCNGXR0stRntMx64s7PBwCcCZL+
wJfuMfEyUyWxv6U77eVnEBw=
=dejV
-----END PGP SIGNATURE-----