Wiki Tools

  • Find Page
  • Recent Changes
  • Page History
  • Attachments

Pieces of bzr, abridged

Intro and Summary

This document describes the fundamental piece bzr works with (the Revision) and the 3 components you deal with in manipulating them (the Repository, the Branch, and the Working Tree).

This article doesn't attempt to be complete and comprehensive, but rather to give the initial feel for the pieces. The PiecesInLength article picks up where this leaves off and delves into more details.

For simplicity, and to keep this from being 200 pages long, I'm making no attempt to rigorously define each term before I use it. Hopefully, the intended semantics of non-previously-defined terms are nonspecific enough for this to not trip anybody. I also avoid talking about some special cases, to avoid a lot of long and meandering "X is always Y, except when..." digressions. This is supposed to be an introduction.



The Revision is the most basic item that revision control is aimed at.

It's basically a record of a particular state of your files (generally created by a command like commit), with some metadata to keep it straight. Essentially everything you ever do with bzr (or any VCS) is aimed at creating or arranging or examining Revisions.

The following three components are the tools you use to deal with Revisions.


The first of the 3 components you work with in bzr is the Repository.

A Repository is basically a giant bucket, which holds your Revisions. And that's all it does; it's just a container where Revisions are stored. It doesn't do more than that (like impose any structure on them), and there's no place where a Revision can be stored except in a Repository.


The second component is the Branch.

At a conceptual level (which is all we'll mention here; more concrete information comes further down), a Branch defines a particular line of development. It describes a particular sequence of Revisions (first this, then that, then this other...) that are meaningful in a particular case.

Two different Branches can have all of the same revisions (be basically copies of each other), some the same and some different (two divergent bits of work), or no common revisions at all (branches of unrelated projects). The relationship among them is, at the most basic level, just a matter of what Revisions they have in common.

Working Tree

The third component is the Working Tree.

This is where you interact with the files you're versioning. Here is where you add them, delete them, edit them, read them, compile them, and do whatever else you do with files to them. Relating to Revisions, this is your staging area where you create new states that you'll make new Revisions out of.

The term Checkout is often used as a near-synonym for Working Tree.

Components Together

To do much of anything with Revisions, you need all three of the components.

You have to have a Repository, where your Revisions are stored; they can't exist anywhere else. You have to have a Branch, which defines what Revisions in that Repository are of interest and how they arrange. And you have to have a Working Tree where you can examine what already exists and create new things to become new Revisions.

The simplest setup is to have all three colocated together. This is the configuration you get when you run bzr init foo without any external preparation. You get a subdirectory of foo/ called .bzr/ which contains a Repository. It contains a Branch, which refers to Revisions (none at the moment, since you're starting fresh) stored in that Repository. And it contains the meta-files related to your Working Tree, where you can start creating things.

  • There is some ambiguity there, because Working Tree encompasses both the files you're working on (which are directly in foo/ in this example), and some control files where bzr tracks information about them, which are stored under foo/.bzr/ alongside the Branch and Repository pieces. Usually when people use the term Working Tree they refer to your files, not the control files. When they mean the latter, they'll usually say "Working Tree control files" explicitly.

It's not necessary that all 3 pieces be put together like that. You can have a Working Tree and Branch together, but have the Repository somewhere else; this allows a single Repository to be shared by multiple Branches. You could also have the Working Tree somewhere separate from the Branch; this allows various other flexibility. But most of the time when you're doing anything with bzr, you have all 3 pieces somehow connected, with a Working Tree knowing what Branch it's connected to, and the Branch knowing what Repository it's using. Whether they're all in one place, or scattered all around the system (or even across a network), they're all involved.

For Additional Confusion

By a quirk of history and naming, that whole conglomeration (Repository, Branch, and Working Tree) is often colloquially called a "branch". People will say things like "now cd into the branch, and edit your files"; of course you don't edit files in a Branch, you edit them in a Working Tree. So it can take some deciphering to figure out what, strictly speaking, is being called for.

Unfortunately, I don't know of any shortcuts to understanding exactly what piece someone is talking about. As with any topic, sometimes words that have very precise meanings are used in fuzzier ways. When you have a good understanding of bzr, it's rarely a problem to know what is meant. Until then, just remember that when somebody talks about doing something with a branch, they may not necessarily be talking precisely about the component Branch.

Conversely, when *you* talk about working tree, branch or repository ignoring the common definitions agreed upon in the bzr community, you may be misunderstood. Hopefully the definitions given above are simple enough to grasp and should allow all parties to better communicate.

Components Redux

Now, we've got the foundation to talk about the pieces in more detail.