Checkouts

Checkouts are source trees that are connected to a branch, so that when you commit in the source tree, the commit goes into that branch. They allow you to use a simpler, more centralized workflow, ignoring some of Bazaar’s decentralized features until you want them. Using checkouts with shared repositories is very similar to working with SVN or CVS, but doesn’t have the same restrictions. And using checkouts still allows others working on the project to use whatever workflow they like.

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 copy for you that still contains a reference to the branch you created the checkout from (the master branch). Then if you make any commits they 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. 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. All the local commits will then be made on the master branch the next time you do a non-local commit.

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 applied before any non-local commit, but Bazaar will tell you if there are any changes and suggest that you use this command when needed.

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.

Lightweight checkouts work best when you have fast reliable access to the master branch. This means that if the master branch is on the same disk or LAN a lightweight checkout will be faster than a heavyweight one for any commands that modify the revision history (as only one copy of the branch needs to be updated). Heavyweight checkouts will generally be faster for any command that uses the history but does not change it, but if the master branch is on the same disk then there won’t be a noticeable difference.

Another possible use for a checkout is to use it with a treeless repository containing your branches, where you maintain only one working tree by switching the master branch that the checkout points to when you want to work on a different branch.

Obviously to commit on a checkout you need to be able to write to the master branch. This means that the master branch must be accessible over a writeable protocol , such as sftp://, and that you have write permissions at the other end. Checkouts also work on the local file system, so that all that matters is file permissions.

You can change the master of a checkout by using the “switch” command (see “help switch”). This will change the location that the commits are sent to. The “bind” command can also be used to turn a normal branch into a heavy checkout. If you would like to convert your heavy checkout into a normal branch so that every commit is local, you can use the “unbind” command. To see whether or not a branch is bound or not you can use the “info” command. If the branch is bound it will tell you the location of the bound branch.

Related commands:

checkout    Create a checkout. Pass --lightweight to get a lightweight
            checkout
update      Pull any changes in the master branch in to your checkout
commit      Make a commit that is sent to the master branch. If you have
            a heavy checkout then the --local option will commit to the
            checkout without sending the commit to the master
switch      Change the master branch that the commits in the checkout will
            be sent to
bind        Turn a standalone branch into a heavy checkout so that any
            commits will be sent to the master branch
unbind      Turn a heavy checkout into a standalone branch so that any
            commits are only made locally
info        Displays whether a branch is bound or unbound. If the branch is
            bound, then it will also display the location of the bound branch