Table of Contents (3.3.22)

# Organizing branches

## Mirror branches

A primary difference when using distributed workflows to develop is that your main local branch is not the place to make changes. Instead, it is kept as a pristine copy of the central branch, i.e. it’s a mirror branch.

To create a mirror branch, set-up a shared repository (if you haven’t already) and then use the `branch` (or `checkout`) command to create the mirror. For example:

    brz init-shared-repo PROJECT
    cd PROJECT
    brz branch bzr+ssh://centralhost/srv/brz/PROJECT/trunk

## Task branches

Each new feature or fix is developed in its own branch. These branches are referred to as feature branches or task branches - the terms are used interchangeably.

To create a task branch, use the `branch` command against your mirror branch. For example:

    brz branch trunk fix-123
    cd fix-123
    (hack, hack, hack)

There are numerous advantages to this approach:

> 1. You can work on multiple changes in parallel

> 2. There is reduced coupling between changes

> 3. Multiple people can work in a peer-to-peer mode on a branch until it is ready to go.

In particular, some changes take longer to cook than others so you can ask for reviews, apply feedback, ask for another review, etc. By completing work to sufficient quality in separate branches before merging into a central branch, the quality and stability of the central branch are maintained at higher level than they otherwise would be.

## Refreshing a mirror branch

Use the `pull` command to do this:

    cd trunk
    brz pull

## Merging the latest trunk into a feature branch

Use the `merge` command to do this:

    cd fix-123
    brz merge
    (resolve any conflicts)
    brz commit -m "merged trunk"

## Merging a feature into the trunk

The policies for different distributed workflows vary here. The simple case where all developers have commit rights to the main trunk are shown below.

If your mirror is a checkout:

    cd trunk
    brz update
    brz merge ../fix-123
    (resolve any conflicts)
    brz commit -m "Fixed bug #123"

If your mirror is a branch:

    cd trunk
    brz pull
    brz merge ../fix-123
    (resolve any conflicts)
    brz commit -m "Fixed bug #123"
    brz push

## Backing up task branches

One of the side effects of centralized workflows is that changes get frequently committed to a central location which is backed up as part of normal IT operations. When developing on task branches, it is a good idea to publish your work to a central location (but not necessarily a shared location) that will be backed up. You may even wish to bind local task branches to remote ones established on a backup server just for this purpose.