Getting a Branch object

In order to operate on your branch, you'll need to create a Branch object. This will be a programmatic handle to your bzr branch itself. So let's start by getting the branch itself.

from bzrlib.branch import Branch

my_branch = Branch.open('/path/to/branch')

Now we can operate on the branch with python. Let's say we want to see what config variables are set on this branch. We'll want to get the configuration of the branch, and then examine its contents. In this example, we'll check the username you'll be committing to bzr with (because you hopefully ran bzr whoami.

my_branch_config = my_branch.get_config()
print my_branch_config.username()

Simple local branching

Let's say you want to programatically create a local copy of a remote branch.

from bzrlib.branch import Branch

remote_branch_url = 'bzr+ssh://bzr.eventuallyanyway.com/code/foo-bar-baz'

remote_branch = Branch.open(remote_branch_url)
local_branch = remote_branch.bzrdir.sprout(
    '/code/foo-bar-baz').open_branch()

Getting a diff

Programmatically, I think the best use for understanding the Bazaar API is to diff the changes in your current working tree. You'll do this by creating a WorkingTree object and operating on it.

from bzrlib.workingtree import WorkingTree

tree = WorkingTree.open('/code/foo-bar-baz')

Now you've got a working tree. Let's get a diff between it's current state and its last committed state. If it's changed, commit the changes with a commit message of "Committed changes"

delta = tree.changes_from(tree.basis_tree())
if delta.has_changes:
    tree.commit('Committed changes')

All in all, I think the greatest strength of Bazaar is its easy extensibility, and easy entry into working with its API is proof.

Creating a merge proposal with email

Looking back on the general Launchpad branch configs we used, we need to add one more line so that Bazaar knows the email address that Bazaar's "bundles" should go to. So, let's edit our ~/.bazaar/locations.conf to show the following:

[/home/rockstar/Projects/repos]
push_location = lp:~rockstar/
push_location:policy = appendpath
public_branch = lp:~rockstar/
public_branch:policy = appendpath
submit_to = merge@code.launchpad.net

The line added is the submit_to line. This means that Bazaar is going to send its bundles to merge@code.launchpad.net. This is the email address that parses the bundle, and derives the the source branch (the branch to be merged) and the target branch (the branch to merge into).

Now we need to specify the submit branch. This requires some specific configs for each project, so we'll need to add a new section. For this example, we're going to use Entertainer since Bazaar's development doesn't use Launchpad for it's review process. I'm going to add another section specific to Entertainer.

# Entertainer
[/home/rockstar/Projects/repos/entertainer]
submit_branch = lp:entertainer

This sets all branches in ~/Projects/entertainer to submit to the branch lp:entertainer which happens to be the current development focus of Entertainer. Note: The target branch MUST be a Launchpad branch. The source branch doesn't really need to be, and Launchpad is smart enought to create a Remote branch (a branch that Launchpad only keeps a reference of).

Finally, we need to tell Bazaar what your preferred email client is. So crack open ~/.bazaar/bazaar.conf and let's add one more line to the [DEFAULT] section.

mail_client = evolution

Wait. You don't want to use evolution to send your email? Well, you can choose between thunderbird, evolution, kmail, thunderbird, mutt, emacsclient (although I don't know how that emacsclient works), or editor. I use editor, but that requires some more config set up (and it's beyond the scope of this post). Also, if you want to use Gmail, see BzrSendWithGmail or use James Henstridge's bzr-imapclient plugin to use GMail to send the merge-directive (see https://lists.ubuntu.com/archives/bazaar/2009q1/051602.html. As of Bazaar 1.11, bzr also now supports claws as a mail_client as well.

Now, hacka hack on your branch, and when it's all ready, make sure it's pushed to Launchpad, and then do bzr send --no-bundle. This will create a bundle and open up your mail client for you to detail what your branch does. Fill that out, and send the email. It'll be processed, and the merge proposal will be created, using the Default Reviewer for the target branch as the reviewer.

Reviewing a branch through email

This is where things get more interesting. Those subscribed to the branch (as branch code reviewers should be) will get an email with the creation of the merge proposal, and an email with the patch (these two emails will be consolidated shortly).

So a reviewer cracks open the email and looks through the patch. They merge the branch into their local mirror of trunk and run the tests (because you have tests for code, right?). The reviewer makes their inline comments to the patch in the email reply. The To: in their reply should be something like mp+1234@code.launchpad.net.

If you (as reviewer) were to send this email now, it'll be parsed as a comment to the merge proposal. What if you want to give an official review vote? What if you want to set the merge proposal status to Approved? This is the clever part. For example, I review a branch and I think it needs to be set to Needs Fixing. Within the email, I would type:

vote needs_fixing

Note the leading space there. It's important. Now, GPG sign your email, and send it off. You've just given your vote. After someone decides to fix the issues that arose from your review, you can reply to the response email with:

vote approve
status approved

Send this with a GPG signed email, and you've updated the merge proposal to Approved as well as "voted" approve. Now, if you can merge the branch, merge it, otherwise, nudge someone who can.

Hooray! You've successfully navigated the hairy process of code review without having to hassle with the web UI at all. Now THAT'S a service worth working with. There are similar commands to work with bugs as well, and by learning to use these commands, you can create a workflow with Launchpad that works best for you.

Update: Thanks to some great comments, I've noted some of extras.