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).

Comments