Since all the branch operations work transparently and consistently between remote and local branches, you can work with remote branches directly. However, it is often more practical to work with remote branches in an indirect way, using mirror branches. For example:
- You can speed up branch operations by using local mirror branches instead of working with a remote branch directly
- If your collaborators don't have direct access to your local branches, you can provide remote mirror branches at a more accessible location.
In this section, we will explain various practical considerations when working with remote branches. In particular, it is important to become very comfortable with the various mirroring operations in order to work with remote branches with ease.
All the branch operations work exactly in the same way with remote branches as with local branches. For example:
bzr info REMOTE_URL: This prints basic information about the remote branch.bzr log REMOTE_URL: This shows the revision history of the remote branch.bzr qlog REMOTE_URL: This shows the revision history of the remote branch in Bazaar Explorer.bzr branch REMOTE_URL [TO_LOCATION]: This creates a new local branch as a perfect replica of the specified remote branch. The second parameter can be used to specify the path of the new local branch, otherwise the branch is created as a subdirectory in the current directory.bzr missing REMOTE_URL: This compares the current branch with the specified remote branch and prints the list of missing revisions in both.bzr diff --new REMOTE_URL: This compares the current branch with the specified remote branch and prints the differences going from the current branch to the remote branch. Use--old REMOTE_URLto show the differences in the other direction.bzr merge REMOTE_URL: This merges the specified remote branch into the current branch.bzr remerge [FILE...]: This performs a redo of the merge, possibly using a different merge algorithm on all files or selected files only.bzr push REMOTE_URL: This makes the remote branch a mirror of the current branch. It works only if the two branches have not diverged.bzr pull REMOTE_URL: This makes the current branch a mirror of the remote branch. It works only if the two branches have not diverged.
However, keep in mind that due to the overhead of transferring data over the network, all these operations will be slower as compared to when working with local branches.
When working with remote branches, the transport over the network poses an overhead—all branch operations are slower because the data must travel over the network. In addition, when working with the same remote branches repeatedly, it can be tedious to re-enter their possibly long and complicated URLs.
In such situations, instead of working with a remote branch directly, it is more practical to create a local mirror branch and perform branch operations using the local mirror instead of the remote branch. Provided that the remote branch has not changed since the local mirror was created, the result of all branch operations will be equivalent regardless of using the remote branch directly, or its local mirror.
This is especially practical when merging from a remote branch. Before performing the merge, you might want to run a series of commands to inspect the branch; for example, using the bzr log, bzr missing, and bzr diff commands, or their equivalents in Bazaar Explorer. After performing the merge you might want to redo the merge with bzr remerge by using a different algorithm.
Running multiple commands directly on a remote branch while it hasn't changed is inefficient, as Bazaar would have to transfer data over the network repeatedly. A more efficient way is to first create a local mirror, and perform all the branch operations you may need on the local mirror instead of the remote branch.
You can create a local mirror by simply creating a local branch based on a remote branch, by using the bzr branch command or its equivalent in Bazaar Explorer.
The local branch will be identical to the original remote branch, and the result of all branch operations using the local branch as the source branch will be identical to using the remote branch directly, but more efficient because the network overhead is completely eliminated.
Keep in mind that the local branch is only a mirror as long as you use it that way. Technically speaking, a mirror branch is no different from any of your other local branches. If you make changes and commit new revisions to a mirror branch, it will have diverged from its parent. If you keep it as a pristine copy without committing any new revisions to it, then you will be able to bring it up-to-date with its parent later.
When working with multiple branches, it is always a good idea to use a shared repository, as this eliminates the unnecessary copying of revision data between branches, saving disk space and speeding up branch operations.
Using a shared repository is especially useful when creating new local branches based on remote branches, because Bazaar can re-use the revisions that already exist in the shared repository, thus reducing the amount of data transferred over the network, greatly mitigating the network overhead.
A local mirror branch is not updated automatically when new revisions are added in its parent branch. This comes from the fact that a mirror branch is no different from any other branch—a local branch is only a mirror because you use it that way.
To bring a local branch up-to-date with its parent, use the bzr pull command, or in Bazaar Explorer the large Pull button in the toolbar.
This works only if the local branch has not diverged from its parent; that is, you have not committed any new revisions to it yourself. The pull operation only makes sense between branches that have not diverged, otherwise Bazaar will fail with an error, since the local branch is no longer a mirror of its parent.
As long as the local branch is not changed in another way, you can pull from its parent branch repeatedly, to download any new revisions that may have been added at the remote side. If the local branch is already up-to-date, pulling again will simply do nothing.
Branches that you create on your computer are normally not accessible by others. In order to collaborate with others, you need to make your branches available to them somehow.
Providing direct access to your local branches can be difficult or often impossible due to the network topology between your computer, and the computers of your collaborators. A common solution is to provide remote mirrors of your local branches at a location that is accessible by your peers. Since a remote mirror branch is identical to its parent branch, your collaborators can work with the mirror branches and get the same result of all branch operations as if they were accessing your local branches directly.
You can create a remote mirror branch from the current branch by using the bzr push command and specifying a remote URL that supports write operations, such as bzr://, bzr+ssh://, and ftp://, aftp://. For example:
$ bzr push bzr://example.com/path/to/create $ bzr push bzr+ssh://[email protected]/path/to/create $ bzr push aftp://[email protected]/path/to/create
Of course, in order to try these operations, you need to have access to a remote server that is configured appropriately. See the explanation earlier in the Sharing branches section.
When creating multiple remote branches on the same server, it is always a good idea to use a shared repository, as this eliminates the unnecessary copying of revision data between branches, therefore saving disk space and speeding up branch operations.
Using a shared repository is especially useful when creating new remote branches, because Bazaar can re-use the revisions that already exist in the remote shared repository, thus reducing the amount of data transferred over the network and greatly mitigating the network overhead.
A remote mirror branch is not updated automatically when new revisions are added in its parent branch. This comes from the fact that a mirror branch is no different from any other branch—a remote branch is only a mirror because you use it that way.
To bring a remote branch up-to-date with its local parent, use the bzr push command, or in Bazaar Explorer the large Push button in the toolbar.
This works only if the remote branch has not diverged from its parent. The push operation only makes sense between branches that have not diverged, otherwise Bazaar will fail with an error, since the remote branch is no longer a mirror of its parent.
As long as the remote branch is not changed in another way, you can push to it from the same local branch repeatedly, to upload any new revisions that you have added locally. If the remote branch is already up-to-date, pushing again will simply do nothing.
If you intend to use a branch as a mirror, then it makes sense to skip creating a working tree. By default, Bazaar creates a working tree in new branches, but a working tree is optional in general, and you can save disk space and speed up operations by not creating it.
To create a branch
without a working tree, use the --no-tree flag with the bzr branch command. For example:
$ bzr branch lp:~bzrbook/bzrbook-examples/hello-start --no-tree Branched 6 revisions.
The directory of the new branch created in this way is not populated with files; you will find only the .bzr directory inside and none of the files of the project. All the branch operations will work with such a branch, except operations that require a working tree such as the bzr add, bzr remove, and bzr commit commands.
You can
use the bzr reconfigure command to create or remove the working tree from the directory of an existing branch.
To remove an existing working tree from a branch, use the --branch flag. For example:
$ bzr reconfigure --branch
To create a working tree in a branch that doesn't have one, use the --tree flag. For example:
$ bzr reconfigure --tree
Within a shared repository, branches without a working tree are called repository branches, and branches with a working tree are called a repository tree. Outside a shared repository, branches without a working tree are called standalone branches, and branches with a working tree are called a standalone tree:
|
With working tree |
Without working tree | |
|---|---|---|
|
Shared repository |
Repository tree |
Repository branch |
|
Standalone |
Standalone tree |
Standalone branch |
You can confirm the configuration of a branch by using the bzr info command. The first line of the output tells the name of the configuration. For example:
$ bzr init /tmp/branch --no-tree Created a standalone branch (format: 2a) $ bzr info /tmp/branch/ Standalone branch (format: 2a) Location: branch root: /tmp/branch $ bzr reconfigure --tree /tmp/branch/ $ bzr info /tmp/branch/ Standalone tree (format: 2a) Location: branch root: /tmp/branch
In the default setup of a
shared repository, new branches are created with a working tree. You can change that behavior using the --with-no-trees and --with-trees flags.
To turn off working trees by default:
$ bzr reconfigure --with-no-trees
To turn on working trees by default:
$ bzr reconfigure --with-trees
The configuration with working trees enabled is called shared repository with trees, and without working trees is called simply
shared repository. You can confirm the configuration of a shared repository using the bzr info command; the first line of the output tells you the name of the
configuration. For example:
$ bzr init-repo /tmp/repo Shared repository with trees (format: 2a) Location: shared repository: /tmp/repo $ bzr reconfigure --with-no-trees /tmp/repo/ $ bzr info /tmp/repo/ Shared repository (format: 2a) Location: shared repository: /tmp/repo
The working trees setting affects the default behavior of the bzr branch and bzr push commands when used to create branches within the shared repository. Changing the setting has no effect on existing branches; you must use the bzr reconfigure command explicitly to create or remove working trees in the existing branches.
When creating a remote branch, by default, Bazaar will try to create a working tree if the protocol supports it. Use the --no-tree flag to override this behavior and skip creating a working tree.
When creating remote branches for the purpose of mirroring, it is usually better to skip creating a working tree for two reasons:
- Save disk space and speed up push operations
- Remote mirror branches are meant to be used in branch operations only, thus having a working tree is pointless and may become confusing
When working with multiple local and remote branches, it is important to be fully comfortable with mirroring branches locally or remotely. In order to master these operations, perhaps it helps to play around with them to see how they can be combined in different ways that result in perfectly equivalent branches.
Given two branches branchA and branchB that have a common base revision (common ancestor) but have diverged in different directions, let's define a few additional branches to work with:
- Let
branchA_Bbe the result of merging frombranchBtobranchA - Let
branchB_Abe the result of merging frombranchAtobranchB - Let
branchA_oldbe the result of branching frombranchAat a past revision - Let
branchB_oldbe the result of branching frombranchBat a past revision
Then the following statements are all true:
- The result of
bzr branch branchA_B -rlast:2is identical tobranchA - The result of
bzr branch branchB_A -rlast:2is identical tobranchB - The result of
bzr pull -d branchB branchA_Bis identical tobranchA_B - The result of
bzr pull -d branchA branchB_Ais identical tobranchB_A - The result of
bzr push -d branchA_B branchBis identical tobranchA_B - The result of
bzr push -d branchB_A branchAis identical tobranchB_A - There is a revision
REVinbranchA_Bsuch that the result of bzrbranch -rREV branchA_Bis identical tobranchB - There is a revision
REVinbranchB_Asuch that the result ofbzr branch -rREV branchB_Ais identical tobranchA - The result of
bzr push -d branchA_B branchA_oldis identical tobranchA_B - The result of
bzr push -d branchB_A branchB_oldis identical tobranchB_A
To verify the preceding statements, you can recreate the branches in the original assumptions, or download our sample branches using the following commands:
$ bzr init-repository /tmp/slicing-and-dicing $ cd /tmp/slicing-and-dicing $ bzr branch lp:~bzrbook/bzrbook-examples/branchA_B $ bzr branch lp:~bzrbook/bzrbook-examples/branchB_A $ bzr branch branchA -rlast:3 branchA_old $ bzr branch branchB -rlast:3 branchB_old
Based on these branches you can verify all the preceding statements, make comparisons, and test your own assumptions. For example:
bzr missing: This should print an empty output for equivalent branchesbzr diff: This should print an empty output for equivalent branchesbzr merge: This should printNothing to do.if branches are equivalentbzr push: This confirms when it is possible to push and when not, and the result of the push operationbzr pull: This confirms when it is possible to pull and when not, and the result of the pull operation
Going through these examples should solidify your understanding of the branch, push and pull operations, and thereby enable you to slice and dice branches at ease.