Friday, June 27, 2008

14 Bazaar Howtos

Howto 1 - Tell Bazaar Who You Are

Bazaar will add your identifier information to your commits.

$ bzr whoami "Phil Larson <phil.larson@gmail.com>"


Howto 2 - Create Local Project Folder

This step is not technically necessary for Bazaar, but I think it is helpful. First you should create a project folder on your machine that should probably match the name of the project on the server. So I'll do something like this:

$ mkdir ~/Code/projectfoo


Howto 3 - Checkout The Trunk

Bazaar has two ways of making a "working copy." The most general way is making a branch of another branch, I will show that later. For the trunk, I find it useful to have an in sync copy of the server. Bazaar calls this a checkout, and it works similarly to a Subversion checkout. Any commits made on the working copy automatically get copied to the published branch on the server.

$ bzr checkout sftp://bzr@mysourceserver.com/var/bzr/projectfoo/trunk/ ~/Code/projectfoo/trunk


Howto 4 - Make A Feature Branch

When you want to start working on a new feature, make a branch off the trunk and give it a descriptive name. This name is local and private to your machine so you don't have to worry about conflicts or a specific naming convention.

$ bzr branch ~/Code/projectfoo/trunk ~/Code/projectfoo/featureA


Howto 5 - Make Changes On Feature Branch As Needed

Now you can make changes as usual to get your feature working.

Howto 6 - Tell Bazaar To Add, Rename, or Move

When you do anything that changes the path of the file, you should let Bazaar do it for you:
Add
This lets you add specific files to version control.
$ bzr add README.txt

Add All
This lets you add all non-versioned files to version control.
$ bzr add

Create a folder and add it
This allows you to create a folder and add it at the same time
$ bzr mkdir docs

Move/Rename
Moving and renaming is the same command, just like a Unix shell.
$ bzr mv README.txt docs/README.txt


Howto 7 - Automatically Detect Deletes

Bazaar will automatically find missing files and mark them as deleted when you commit.

Howto 8 - Commit Changes Often And Early

As you make units of changes, you can commit them on the branch with a message. This gives you a history of what you did, and the chance to roll back.

You can set up your EDITOR environment variable to have your editor launch and let you edit the commit message.

Or you can specify the message inline like this:

$ bzr commit -m 'My commit message'


Howto 9 - Merge Changes From The Trunk

As changes happen on the trunk they won't be pulled into the feature branch. To get the changes into the feature branch:

$ cd ~/Code/projectfoo/trunk
$ bzr update
$ cd ../featureA
$ bzr pull ../trunk


Howto 10 - Prepare To Merge Changes To The Trunk

First thing to do is make sure there are no outstanding changes on the trunk:

$ cd ~/Code/projectfoo/trunk
$ bzr status


Then you want to make sure you have the latest version of the trunk

$ cd ~/Code/projectfoo/trunk
$ bzr update


Howto 11 - Merge Changes Into The Trunk

When you get your feature branch how you want it, then it's time to merge into the trunk.

$ cd ~/Code/projectfoo/trunk
$ bzr merge ../featureA

This will apply the changes from the feature branch to your trunk working copy. Then you should compile and run tests on the trunk to make sure there are no conflicting changes. When you are satisfied that the merge completed successfully, commit like normal. Since the trunk is a checkout, not a branch, it will send the changes to the server so other people can access them.

Howto 12 - Publish A Branch

If you want your branch to exist on the server for whatever reason, you can push it to the server.

$ cd ~/Code/projectfoo/events
$ bzr push ssftp://bzr@mysourceserver.com/var/bzr/projectfoo/events/

From now on the url will be recorded as a push location. So in the future you can just run the shorter command to update the published branch.

$ bzr push

This branch is the same as the trunk branch, so you can make a checkout style working copy as well if you want.

Howto 13 - View Changes

If you're on a Mac and you have the Developer Tools installed, you can ask bzr to open up a FileMerge window with the current changes that haven't been committed:
$ bzr diff --using opendiff


You can also view the diff between different revisions:
$ bzr diff -r1..10 --using opendiff


Or for specific files:
$ bzr diff -r1..10 --using opendiff README.txt


For the other combinations read:
$ bzr help diff


Also there are other tools that are valid for the 'using' parameter. Some examples of supported diff tools include 'kdiff3', 'kompare', 'meld', 'vimdiff', and 'xxdiff'.

Howto 14 - Use The Docs

Bookmark the Bazaar Reference Guide

3 comments:

... said...

Thanks, useful.

Please add some more Howtos for creating repositories.

First you say "co", but didn't say "co" what?!

Randall Smith said...

Thanks for the post. One thing I found out though on the OS X machine I'm using is I need the difftools plugin installed which can be installed by issuing the command "bzr branch lp:bzr-difftools path-to-plugins-directory". Just posting this incase anybody else had the same problem.

Peter Balazovic said...

i just find it recently. I'd like to start working as suggested http://stackoverflow.com/questions/2367453/recommended-mercurial-repository-folder-structure-for-an-svn-user
is there a way how to do under bazaar, or do you have other recommendation?
Thanks