I wish this was in huge type on the front page of the Bazaar web site because it is essential to understanding just what the heck is going on when you place you files under version control.
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 folder named after my project, say ‘foo/’, and in folder ‘foo/’ I might 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 initialise Bazaar, ‘bar.py’ and ‘data.py’ will make up my working tree – the files I actually edit.
Branch
The next thing I do is initialise 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.
A branch 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.
Repository
Among other things, ‘.bzr/’ contains a folder called ‘repository’. This, not surprisingly, is your repository – the place where all commited changes to your working tree are stored.
There isn’t much to a repository until you run ‘bzr add’, which adds all the files and folders in your project to the branch, and ‘bzr commit’ which records all the changes to your working tree in your repository.
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. A common thing to do if you have more than one person working on your project is to use the same repository for everyone. The command ‘bzr init-repo’ (as opposed to just plain old ‘bzr init’) creates a shared repository.
Checkout
So I created a folder and put some files in it, then initialised Bazaar which made my project a branch. Then I ran ‘bzr add’ and ‘bzr commit’ to add the files in my working tree and revisions therein to my branch. Now suppose someone else wanted to add code to my project? That is where checkout comes in.
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.