The difference between a working tree, repository, branch, and checkout in the Bazaar version control system

I love using Bazaar for version control! It allows me to work on the same files as my buddies without accidentally overwriting their work. I’m also free to experiment and refactor without fear, because I can just revert my files to previous (working) version if I screw everything up.

The key to understanding version control is grokking a few basic concepts: working tree, repository, branch, commit and checkout.

I’m going to use an example to explain this. These events are listed in the order that they usually occur, at least when I use Bazaar. If you want to understand this at all, you better read the Bazaar in five minutes tutorial first.

Working Tree

When I start a new project I usually create a directory named after my project, say foo/, and in folder foo/ I put my first file I’ll be working on called, say, bar.py, and a file to hold some data called data.py.  So as soon as I initialize Bazaar, bar.py and data.py will make up my working tree – the files I actually edit.

Branch

If this is the first time I’ve used Bazaar, I need to tell it who I am so it knows to attribute commits to me: bzr whoami "Ammon Morris <me@example.com>"

I initialize Bazaar by typing the command bzr init in the terminal, which creates a hidden folder in the foo/ directory called .bzr/. This hidden folder and its contents is a branch – the state of a project including all its history.

The branch is what you download when you checkout an existing project. It usually includes a working tree too, but it doesn’t have to. If you get a branch and it doesn’t have a working tree, you can run ‘bzr update’ to make one.

Here’s a tip: If you want to take a project off version control, all you have to do is delete the .bzr/ directory, which removes your branch but leaves your working tree alone.

Repository

Among other things, the .bzr/ directory contains a folder called repository/. This, not surprisingly, is your repository – the place where all committed changes to your working tree are stored.

Your repository works like a database. Each file you put under version control gets a unique identifier and each commit is numbered so you can go back to any revision and see what you did (Tip: you can review your revision history with bzr log).

Because all your changes are recorded in the repository, its easy to roll back your files to a previous version. It’s best to do this file by file instead of reverting the whole project:

bzr revert filename

This command will revert the working tree version (the file you edit) of filename to its state at the last commit you made.

Commit

There isn’t much to a repository until you run bzr add, which adds all the files and folders in your project to your repository. Now you get to make your first commit, which saves changes in your working tree to your repository. A commit looks like this:

bzr commit -m "my commit message"

It’s good to get into the practice of making a commit every time you complete a task in your project. Write a function? Make a commit. Fix a bug? Make a commit. It’s fast and easy, so do it early and often. The commit message is very handy when your reviewing your bzr log. It becomes a personalized record of all your changes.

Checkout

So I created a directory for my project and put some files in it, then initialized Bazaar which made my project a branch. Then I ran bzr add to place my files in the repository and bzr commit -m "my commit message" to commit my fist changes (which was just adding files in this case). Now suppose someone else wanted to add code to my project? That is where checkout comes in.

Ed. Note: – If you’re using Bazaar for web development you can skip the rest of this and head right over to the excellent Bazaar In Five Minutes for Web Devs tutorial. I highly recommend the work flow in that tutorial. It works especially well in the likely scenario that several people will be contributing to a project, but only one of you is operating Bazaar.

If the hobo living behind the Safeway wants a stand-alone version of my branch that he can stare at or create a competing project that has nothing to do with mine, he can run ‘bzr branch [BRANCH_LOCATION] [TO_LOCATION]‘. This will create a copy of my branch on his computer, but his commits will not effect my branch.

But if Sally Smartypants and I are friends and she wants to contribute to my project, she would run bzr checkout [BRANCH_LOCATION] [TO_LOCATION], which would create a copy of my branch on her computer just like the hobo, with the major difference that Sally and my branches share the same repository. So when Sally runs ‘bzr commit’, the changes that she made would be reflected in the branch I have. I won’t see them right away though. If I want Sally’s changes to show up in my working tree, I have to run ‘bzr update’ to sync my working tree with our shared repository.

But what if a storm hits and Sally’s Internet goes down? No prob, her commits will just go on her local repository (since she has a full branch that works all by itself) until she’s back online and runs ‘bzr merge’ to sync up her local repository with the main branch.

Hope that clears things up. I know I’ve learned a lot.