Introduction

This is a fairly basic explanation of using the Bazaar version control system, particularly aimed at people using the Otago University computer science Linux machines, and the workflows common in this environment.

Version control systems (VCS) allow you to store documents, code, and whatever else you like in a centralised place. They track the changes that you make, and ensure that you have one canonical version of everything. This means that when you realise that today's changes irreparably broke your program, you can roll back to what you had yesterday (a few years back, a friend of mine did: 'cc program.c -o program.c' by accident. Had he been using a VCS, he would have lost an hour or so worth of work, not the whole thing). Or, when you do some work from home, and then some from uni, you don't have issues merging both sets.

There are two main types of VCS in common use: centralised and distributed. With centralised, everything is saved on a central repository on a server, and most operations require talking to that server. This is usually fine, but can be a bit annoying if you're working offline for some reason. Subversion is a very commonly used centralised VCS.

Bazaar (bzr) is a distributed VCS. Most of the extra features that come from this really shine when working on a project with a number of different people, but there are a few even when it's one person working on their own project. Using bzr doesn't require a central repository (although, most uni work probably is best off with one), and every place you work has it's own copy of the repository (called a 'branch'). It then provides tools that allow these branches to be merged.

Setting Up

Installing bzr.

This is specifically for the Linux machines at uni. On your own Linux machine, you can probably install it straight from the repositories. On Windows, you're on your own (although there is an installer for it.)

This installs it into a directory called 'local' in your home dir, which helps keep things clean and tidy. Things starting with '$' are commands to do in the terminal. I assume you know a little bit about using the terminal, like going to the right directory and so on.

Download the source release from http://bazaar-vcs.org/Download
$ tar xvf bzr-1.12.tar.gz
$ cd bzr-1.12/
$ python setup.py install --home ~/local
Once installed, add ~/local/bin to the path, and ~/local/lib/python to the python path by putting these lines near the end of your .bashrc:
```
    export PATH=$HOME/local/bin:$PATH 
    export PYTHONPATH=$HOME/local/lib/python:$PYTHONPATH 
```

This will take effect the next time you open a shell, to make it happen in the current one:

$ . ~/.bashrc

now running bzr should give you some useful output:

$ bzr 
Bazaar -- a free distributed version-control tool
http://bazaar-vcs.org/

Basic commands:
  bzr init           makes this directory a versioned branch
...

If this works, then you're good to go.

Before actually using it

... tell it who you are:

$ bzr whoami "Joe User <joeuser@example.com>"

mostly this is used for log messages and so forth.

Creating a repository

This is where all work you do that is version controlled will live. In this, it'll be called the 'master repository'. You won't actually work on it in here, you may not even see any files in here. That's normal. I suggest creating the repository in ~/bzr with:

$ bzr init-repo --no-trees ~/bzr
Shared repository (format: pack-0.92)
Location:
  shared repository: /home/cshome/r/robin/bzr

(--no-trees stops it putting real files in there, which a) saves space, and b) reduces the temptation to go and mess with things in there)

All your branches will have their master copy in here. The reason for this is that it gets backed up regularly, so in case of failure, it's likely nothing will be lost.

Creating a branch for your project

Start your project wherever it is that you normally do work. Create a directory structure, some template files, or whatever. Once you've got the real basics there, turn it into a branch:

$ bzr init
Created a standalone tree (format: pack-0.92)

then add your files:

$ bzr add
adding thesis.txt
add completed

and then commit:

$ bzr commit -m "Initial import"
Committing to: /home/cshome/r/robin/tmp/bzrdemo/                               
added thesis.txt
Committed revision 1.

(the message after '-m' is optional — if you don't put it there, it will open an editor for you to use.)

Once this is done, you want to put a copy into your master repository (later, we'll link them together so it happens automatically):

$ bzr push ~/bzr/thesis
Created new branch.

in this example, 'thesis' is the name of the branch inside the master repository. It can be whatever you like.

Workflows

There are two main ways of doing things with the projects you'll have here: one person working on a project (most common), or multiple people working on a project (e.g. in the Software Engineering course)

One person

Once the steps above have given you a place to work, and a repository to back things up to, the only thing you need to do is link them together so that doing a commit automatically pushes the changes straight into the master repository:

$ bzr bind ~/bzr/thesis

From now on, whenever you do 'bzr commit', your work gets saved into two places: the branch that you're working in, and the branch in the master repository.

Working remotely

If you want to get a copy of your project from home and work on it, do:

$ bzr checkout bzr+ssh://you@vex.otago.ac.nz/path/to/home/dir/bzr/thesis

replacing parts as appropriate. When you sit down at another machine, use:

$ bzr update

to bring it up to date.

There is no need to run 'bzr bind', as when you do checkout, it is automatically bound.

Working offline

If you will be without internet for a while, and want to be able to commit changes still, do:

$ bzr unbind

now any commits will happen locally only. When you return to civilisation, run:

$ bzr bind

(no path needed, it remembers.) Then you'll need to update, and commit to the master repository:

$ bzr update
$ bzr commit -m "I was in the forest with only a laptop"

Note that what 'unbind' effectively does is switch between the centralised mode in this section, and the decentralised mode in the next. Knowing this can be useful.

Multiple people

When you have many people working on a project, bzr becomes very useful, however it also becomes more complex. The method described here is just one way of doing it, there are more.

Have a single master branch in a repository for the project. This is where all the code that works should end up, and some care should be taken to not put things in there that break it. This branch can be kept anywhere, just make sure that all people in the group can read and write it (this usually involves setting group permissions.)

Each person who is, for example, adding a feature to the program should have a local branch to work on:

$ bzr branch /path/to/master/branch project

This creates a fresh copy of the master branch in the directory called 'project'. You then work on it, committing (locally) as you go, until your feature is ready for other people to look at:

$ bzr push --remember /path/to/master/branch

This will send your changes to the master branch. It will also remember the location, so that in the future you can just say 'bzr push'.

If someone else has been working on stuff, and they've just pushed their changes into the master branch, you can get them with:

$ bzr push --remember /path/to/master/branch

This mode needs no special treatment for being offline, it'll just all work, except for the 'bzr push' (unless the master branch is on the same machine, but you probably shouldn't take that offline if it's used for a group project).

Note that you can also pull directly from another persons branch that they're working on if you want to have a look at the changes they're making that they haven't yet pushed to the main branch.

Other Notes

Good Habits

Commit often.

If everything blows up, the last commit is the most likely point of recovery. Whenever you finish a subsection, or a set of edits, or a small part of a feature, commit it and record what you did.

Use version control a lot, for everything.

If you have a custom LaTeX, Perl, Python, or whatever else configuration, put it into version control so that a) a failed upgrade of something can be rolled back, and b) you can set it up on another computer quickly. If it's not too big, data should be added too. Anything that would be annoying to lose should be put in.

Ignoring files.

You probably shouldn't have all your .o or .class files put into version control, as they will change a lot and can always be regenerated from the source code. See 'bzr help ignore' on avoiding them automatically.

Add files.

When you create more files, add them. Either a 'bzr add' to add everything (if you keep your ignore rules up to date), or 'bzr add file' to add just that one. 'bzr status' will tell you the state of any files and whether they're new, or changed or whatever. You still need to bzr commit after adding files for them to be recorded. Also, 'bzr commit --strict' will refuse to commit if there are unknown files (see bzr help alias if you want to make this default.)

Moving files.

To keep the history on a file, use 'bzr mv' to move or rename them. See 'bzr help mv'.

URLs

All paths and URLs with bzr are interchangeable, where you see '/path/to/branch', this can be replaced with 'bzr+ssh://user@vex.otago.ac.nz/path/to/branch' and visa-versa.

Conflicts

When working with other people, sometimes you'll both edit the same file in a way that bzr can figure out, and so it'll mark it as a conflict. See here: http://doc.bazaar-vcs.org/bzr.dev/en/user-guide/index.html#resolving-conflicts for dealing with them.

More Information

This didn't cover things like looking over changes ('bzr log','bzr diff') and reverting to older versions of things, and such like. The basics of them can be found by running 'bzr help' for common commands, and 'bzr help commands' for the whole lot.

Some typical workflows: http://bazaar-vcs.org/Workflows

A lot more details on everything: http://doc.bazaar-vcs.org/bzr.dev/en/user-guide/index.html

More docs: http://bazaar-vcs.org/Documentation

BzrForUniWork