A lightweight checkout is a special configuration with only a working tree and a branch, but without a repository. In this configuration, the branch is bound to another branch, named the master branch, in the same way as in a regular checkout. Since there is no local repository, all the operations that access the revision data must go through the master branch. In practice, this has the following consequences:
- The checkout operation is much faster as compared to a regular checkout or branching, because the full revision history is not copied over from the master branch.
- Operations using the revision history must access the master branch. If the master branch is remote, then all such operations must go across the network.
- Since there is no local repository, it is not possible to commit locally. All commits are applied to the master branch.
A lightweight checkout can be a suitable option if the branch history is huge, but you have very fast and reliable remote access. Another possible use occurs when you want to get just the working tree of a project quickly and you don't intend to use operations that involve the revision history.
Throughout the examples using lightweight checkouts, we will use a shared repository at /sandbox/light and the branch /sandbox/light/sample created with the following commands:
$ bzr init-repository /sandbox/light Shared repository with trees (format: 2a) Location: shared repository: /sandbox/light $ cd /sandbox/light $ bzr branch lp:~bzrbook/bzrbook-examples/hello-start hello Branched 6 revisions.
To create a lightweight checkout, use the bzr checkout command with the --lightweight flag:
$ bzr checkout --lightweight hello light123 $ bzr info light123 Lightweight checkout (format: 2a) Location: light checkout root: light123 checkout of branch: hello shared repository: . Related branches: parent branch: bzr+ssh://bazaar.launchpad.net/~bzrbook/bzrbook-examples/hello-start/
As usual, the first line of the output of bzr info tells the type of the branch; in this case, Lightweight checkout.
To create a lightweight checkout using Bazaar Explorer, click on the large Start button in the toolbar and select Checkout..., or navigate to Bazaar | Start and select the Checkout... option.
You can convert a regular checkout to a lightweight checkout by using the bzr reconfigure command:
$ bzr checkout hello/ checkout123 $ bzr reconfigure --lightweight-checkout checkout123/ $ bzr info checkout123/ Lightweight checkout (format: 2a) Location: light checkout root: checkout123 checkout of branch: hello shared repository: .
Since a lightweight checkout doesn't have a repository, the reconfiguration implies that the local repository of the original checkout must be destroyed. If this cannot be done safely, for example, because there are local commits that have not been applied to the master branch yet, then the reconfiguration will fail, and Bazaar will warn you that you must synchronize first. For example:
$ bzr checkout -rlast:2 hello/ hello-2 $ cd hello-2/ $ bzr reconfigure --light bzr: ERROR: '/sandbox/light/hello-2/' is not in sync with /sandbox/light/hello/. See bzr help sync-for-reconfigure.
As the output says, see bzr help sync-for-reconfigure for more details.
When converting a
branch or a tree configuration to a lightweight checkout, you may need to specify the location of the master branch to bind to by using the --bind-to option. For example:
$ bzr branch hello branch123 Branched 6 revisions. $ cd branch123/ $ bzr reconfigure --light --bind-to ../hello
Without the --bind-to option, Bazaar will try to re-use a previously saved bound location, push location or parent location, in that order.
You can convert a lightweight checkout to other configuration types by using the reconfigure command with the appropriate flag:
Since all the preceding configuration types use a local repository, the reconfigure operation will create a new local repository and copy all the revisions from the master branch. Keep in mind that this may take some time, especially if the master branch is remote.