Description

Bound branches are a way to make sure that both a local branch and a remote branch have the same revisions. This is particularly useful if one likes to work on two machines or if one works on a laptop and then pushes a branch into a public place.

Bound branches in bzr take the place of remote 'checkouts' in systems like CVS or SVN and we refer to them as 'checkouts'. (bzr also supports "lightweight checkouts", which are like local checkouts, and aren't branches at all.)

Bound branches can be stated in simpler terms. When a branch is bound to another branch, the commits for the branch will be applied to the other branch first.

How do I use bound branches?

General description of setting up bound branches

The general workflow looks something like this:

• Push a branch to somewhere else, perhaps your ISP.
• Make sure the pushed branch is up to date

• run bzr checkout LOCATION-OF-REMOTE-BRANCH to get a checkout of the remote branch.

Examples of how to set up bound branches

To checkout a branch over SFTP.

 $ bzr checkout sftp://me@here.com//home/me/somebranch

To turn a regular branch into a checkout:

 $ cd somebranch/
 $ bzr bind sftp://me@here.com//home/me/somebranch/

Committing when the location you are bound to is offline

Several commands such as 'commit' accept a --local parameter which will cause them to perform a local operation, *temporarily* unbinding the branch for the duration of that one command.

 $ bzr commit --local -m 'do something offline'

Updating the remote branch after --local commits

When a checkout is rebound to the master branch, all local revisions will be pushed. If both branches have diverged, you need to merge and commit the remote changes first.

If you want the branch to stop being bound at all

One can unbind a branch by changing into the directory of a bound branch and running:

$ bzr unbind

Questions & answers

mutually bound branches

Is it possible/recommanded to have mutually bound branches? For example, working on two different machines, and keeping the branches synchronized.

madduck:

I would love to see this feature. It would get me one step further to the endeavour of synchronising $HOME.

RobertCollins - no, it is not possible, and not planned. We decided that it was too complex to clearly document to the user to have chains of bound branches, let alone the coding headaches in getting it robust and right in terms of transactionality etc.