Introduction
Bazaar is a distributed GPL revision control system. Bazaar is fast and free, written in Python, with an interface that is easy to use for people familiar with CVS and Subversion.
This tutorial is just a very quick introduction into using Bazaar in the Ubuntu community with projects that utilize the Launchpad. This tutorial will briefly cover checkouts and not branching. Branching has a lot more options, but is not necessary for typical editing, and not necessary for people who do not admin their own branch.
Installation
Installation can be done graphically (i.e. Synaptics in GNOME or Adept in KDE), or it can be done from the command line. Which ever way you choose, the package to install is bzr.
If you are on a team in Launchpad (https://launchpad.net), and will be committing or uploading to a Bazaar branch, the first thing you need to do is register your ssh key. Enter the command line, and type the following commands:
ssh-keygen
Select default settings and select a passphrase to use. This will go through and create a SSH Key. When you are complete, goto your Launchpad account, and select SSH Keys from the table to the left. It will ask you to Add an SSH key and there will be a text box. You need to copy the entire contents of your ~/.ssh/id_rsa.pub and paste it into that box. To do it from the command line, type:
cat ~/.ssh/id_rsa.pub
This will print out a few lines of characters. You want to copy from where it starts ssh-rsa all the way until you see username@hostname. This is what you want to paste and import on Launchpad.
Checkout
Simply for this tutorial, Checkouts will be covered. If you are interested in branching, then you should visit http://bazaar-vcs.org for further details. There is nothing you can do with a Checkout that you can't do with Branches. The only differences are the defaults and work flow helpers.
There are 2 Types of Checkouts
Lightweight Checkout - This type of Checkout is for where the is no local Branch or Repository.
Heavyweight Checkout - This type of Checkout is for when you have copy of all of the RCS information.
In other words, there is a less to download with a Lightweight Checkout due to no "Revision Control Structure", however if more than one person are working on a repository, or it is shared, then a Heavyweight Checkout is the way to go.
For the purposes of this tutorial, we will cover a Heavyweight Checkout.
Instructions
NOTE: All instructions for Bazaar will be carried out via the command line.
Checkout
Locate the branch that you would like to work on. For instance, lets say you want to work on K-D-S (Kubuntu Default Settings) for Kubuntu. In order to do any committing to the the Bazaar repository, you would have to be a Kubuntu Member. This does not stop you from checking out the branch though. Lets go ahead and check out the K-D-S branch.
bzr checkout http://bazaar.launchpad.net/~kubuntu-members/kubuntu-default-settings/ubuntu newcheckoutdir/
This will go through and start downloading the K-D-S branch to your hard drive, in the directory you specified.
Tips & Tricks
The reason for Tips & Tricks is to show you a couple of configuration settings that will make your life much easier with Bazaar.
Whoami
Exactly how it sounds. If you were to go into your new K-D-S directory, and type bzr whoami, it would print out Your Name <email@example.com>, or in many cases username@hostname. Say that you want to use your @kubuntu.org email address when you work on this branch, and this branch only. You would go into the root directory of the local K-D-S branch, and type:
bzr whoami --branch 'Your Name <you@kubuntu.org>'
So now, whenever you upload, or commit, to the K-D-S Bazaar branch, it would post with your name and kubuntu.org email address. You can do this for each branch that you have checked out locally.
Locations
Locations are the push_location links from your local branch to the actual Bazaar repo. Locations are usually stored in your ~/.bazaar/locations.conf file, and resemble:
[/home/username/checkout/location] push_location = sftp://bazaar.launchpad.net/~kubuntu-members/kubuntu-default-settings/ubuntu
If your setup does not look like this, you can edit with a text editor fairly easy. For the push_location, notice that it is sftp now and not http. In order to commit or upload to Bazaar, you have to use the sftp protocol. If you do not set this in your locations.conf, then every time you commit, or push, you will have to specify it via commands, which becomes very tedious after the first couple of times.
Editing
You can go about editing and adding files just like you normally would do with source. The only time you will use Bazaar is to check the branch status, do a branch diff, or add a new file or directory.
Status
This will show the current status of branch files, and if they have been edited, added, and/or removed. To see the status, simply issue, from within the branch root:
bzr status
If there are changes, it will inform you by printing out the current stats to the terminal.
Add
If you add a new file or new directory and would like it to be in revision control, you need to add it to the branch. For example, you added bazaar.rules to the src/ directory, you would type at the command line:
bzr add src/bazaar.rules
This file has now been added to revision control.
Diff
Diff does exactly as it sounds. It lets you know what is different about your checkout compared to the current branch revision. This is the biggest used bazaar command for coders who do not have access to a Bazaar branch to commit or upload to, but need to patch a file or whatever. Using this command, you can create a diff, or a patch, to email to the branch team so they can apply it. To create a patch, simply type at the command line:
bzr diff > patchname
This will create the patch that you can send to the developer for implementation.
Revert
Revert allows you to go back to the previous file prior to you editing it. Say you made changes to a file, but after going through the source, realized you didn't need them changes, you could simply revert it back to its last state. For instance, you want to revert src/bazaar.rules, you would type at the command line:
bzr revert src/bazaar.rules
Commit
Commit rights only come to those who are part of the team that owns the branch. For instance, the K-D-S branch is owned by the Kubuntu Members. So everyone who is listed on https://launchpad.net/people/kubuntu-members has commit rights to the branch. Lets say that you in fact are on the team, and want to commit some changes you made. As long as everything is alright, and you are not getting any errors when issuing bzr stat, then you are ready to commit. Make sure you check over everything prior to committing. To commit, simply type at the command line:
bzr commit -m "commit note - information"
This will upload, or commit, your changes directly to the Bazaar branch on the server. Note that you will not see your changes right away on the tracking page for the branch, that usually takes 15 to 30 minutes to update the information.
Conclusion
Further information on how to use Bazaar can be viewed in the Bazaar Tutorial at http://doc.bazaar-vcs.org/bzr.dev/tutorial.htm. Bug reports and support requests should be filed through Launchpad at https://launchpad.net/products/bzr.
Troubleshooting
bzr: ERROR: Cannot lock: transport is read only: <bzrlib.transport.http._urllib.HttpTransport_urllib url=http://bazaar.launchpad.net/~<your branch>/.bzr/repository/> FIX: Commit locally, and then push to the server.
bzr commit --local -m "Commit Message"
bzr push sftp://bazaar.launchpad.net/~<your branch>
Note: If you added the sftp:// directory in your ~/.bazaar/locations.conf, then you do not need to add the address in the above push.