David Strauss
February 9, 2009

This post is a follow-up to my post about the new Drupal HEAD Bazaar branch hosted at Four Kitchens. This post is written specifically for users of Unix-like systems. You can do the same thing on Windows, but you’ll have to adapt the directions a bit.

For me, my projects are code-based and, hence, mostly a collection of version-controlled branches. So, my “Projects” directory (located at ~/Projects) contains a smattering of branches organized into multi-level directory structures.

In my last post, I noted that shared branch storage is the key to fast branching, good offline access, and efficient disk usage. I even covered a quick way to get it rolling for Drupal branches. But it’s one thing to know how and another to know “best practices,” so I’ll share how I do things.

If you’re like me, you want minimal hassle and maximum flexibility for organizing all of your branches. Fortunately, Bazaar doesn’t just look at the next directory up to find a viable shared branch storage database.

Here’s what happens when you create a branch:

  1. Bazaar checks if the new branch is created using the --standalone option. If so, it doesn’t even worry about the possibility of shared storage, and it stores the branch right there. (I’ve included this option for completeness, and you should only worry about it if you need branch permission control, which is typically not an issue on a workstation.)
  2. Bazaar traverses up the directory tree looking for a viable shared storage location. If one is available, it stores the data there, taking advantage of shared revision history between branches.
  3. If all else fails (and this is the default case), Bazaar stores the data right there with the branch.

Based on rule two, all you need is shared storage somewhere in a writable parent directory. I like to put my branches in ~/Projects, so I create shared storage in ~/Projects by running bzr init-repository ~/Projects. Then, I’m set for any branches created in or below ~/Projects.

If you don’t like to centralize your branches one place, you can run bzr init-repository ~ and have shared storage for any branch, anywhere in your home directory. For those used to Subversion and CVS spewing directories everywhere, I’ll explicitly note that this only creates one directory at the specified shared-storage location.

Once you’ve set up shared storage, you don’t have to think about using it; Bazaar will manage it automatically and transparently. If you’re curious whether it’s working, you can run bzr info from within any branch and look for “shared repository” in the output.

If you want to move your branch
If your branch uses shared storage, it references revisions in the shared storage repository. You can’t move it to another computer using normal filesystem commands and still have it work. If you’d like to make the branch completely independent of its shared storage so you can move it anywhere, run bzr reconfigure --standalone from a directory within the branch. It will copy its revisions to local storage.

A better option for moving branches is to use Bazaar’s own bzr branch command to clone the branch and then delete the original. Then, you don’t have to worry about the possibility of shared storage.

Theory note: This is Bazaar’s version of “cheap branching.” Creating additional branches with shared storage only takes the additional disk space required to create the branch’s new working tree (and even that additional space is only necessary if you choose to create a working tree for the new branch).



I’m wondering how to best use Bazaar for personal version control of my Drupal installation. I’m using AWS, EC2 and the Mercury Project. I thought that it would be cool to version control the changes that I make to my configuration. A few questions: kinda basic :)

• Where do you bzr init? I have root permssions.
• What (which directories/files) do you use bzr to version control for you? Do you add your whole www directory for instance? I had a problem when committing my modules directory. It seemed to hang.
• What’s the best way to store my branches locally?


Where do you bzr init? I have root permssions.

You run it in the root directory of whatever you want to version-control. If you’re on the Mercury project, your web root is already a Bazaar branch.

What (which directories/files) do you use bzr to version control for you? Do you add your whole www directory for instance? I had a problem when committing my modules directory. It seemed to hang.

You generally don’t want settings.php or your files directory committed. The first commit can take a while; later commits take time proportional to the number of changes you’re making.

What’s the best way to store my branches locally?

Just do nothing. bzr init without any other action stores the repository for that branch in the root of that branch.

Hey David,

Thanks. A few more questions if you don’t mind.

I see the Mercury project branch at /var/www. I’m wondering how to set up other branches and to use that existing branch.

• For other branches: does it make sense to set up my own branch at server root (“/”)? That’s what I did originally. Is it ok if that branch contains the Mercury project branch? Alternatively, I could set up different branches per directory that I want to version control, e.g. “/~”.

• To work with the existing Mercury project branch, I’m wondering about the best way to proceed. I don’t plan on submitting any patches to the Mercury project. I do plan on making some typical Pressflow customizations such as installing different modules, themes, etc. I would like to use bzr to version control that so that I can revert to a previous state if something goes awry. Since the Mercury project bzr branch is already in the web root, what do I need to do to begin? Do I need to init and add files, or can I simply commit? Finally, since I don’t plan on pushing my changes to the Mercury project bzr server (Launchpad, I believe), will I be able to pull updates from bzr server.

Initializing Bazaar at the server root (“/”) is a very bad idea unless you know exactly what you’re doing (and what you’re doing probably involves a weird form of system state management). For working with the project Mercury branch, I need to see the output of bzr info from /var/www

Thanks again. You’re right. I was trying to preserve system state, but more of that probably comes from not being too experienced with version control. So, I take it that if initializing bzr at server root is a not a good idea, that if I did want to version control some directories beyond web root, that just initializing at the individual directory level (e.g. /~) is the way to go.

In terms of working with the existing Mercury branch, but making my own changes that I don’t want to push to launchpad, I’m supposing that all will be well if I just have my changes stored locally on my server and don’t push to launchpad. Supposing pulling new changes from LP will work fine?

Here’s the output of bzr info:

bzr info
Standalone tree (format: 1.9-rich-root)
branch root: .

Related branches:
parent branch: http://bazaar.launchpad.net/~pressflow/pressflow/6/

Final question about having**** a branch contain other branches. Does that all work out ok? I.E. Parent branch = web root & child branch = modules

Much appreciated

With that branch configuration, your commits will be stored locally, and you’ll need to merge from Launchpad to stay up-to-date.

“Branches containing branches” can happen in three forms:

(1) Entirely unintegrated. This is just a directory with a .bzr repository within another branch. When you run a command, Bazaar simply searches directory by directory upwards until it finds a directory with a .bzr subdirectory. So, commands run within the inner branch (and, implicitly, outer branch) will affect only the inner branch, while commands run in the outer branch (but not inner branch) will only affect the outer branch.

(2) “Joined.” This is when there used to be two separate branches, but the inner one got grafted as a subdirectory in the outer branch through use of bzr join. Both retain their merge ancestry, but there is only one resulting branch.

(3) Sub-tree. Support for this included but unstable (not listed in help), and it’s a compromise between the first two that keeps the inner and outer branches in their own .bzr revision repositories but allows running commands that simultaneously affect both.

David Strauss
February 9, 2009
David Strauss