Bzr

Template:Unix Bazaar (invoked using the shell command bzr) is a distributed version control system "sponsored by Canonical Ltd., designed to make it easier for anyone to contribute to free and open source software projects."[1].

Cheatsheet

Help!

bzr help commandname

Initialization

init

To create a completely new, empty project dir "foo":

bzr init foo

If the directory "foo" contains a project already and just needs versioning added:

cd foo
bzr init
bzr add .

checkout

To check out a "checkout"/working tree (bzr terminology for a working copy) of an existing branch:

# co = checkout
bzr co fooFrom [fooTo]

If there is no fooTo, the last fragment of fooFrom is used.

branch

To start an entirely new branch copied from an existing branch:

# branch = get = clone
bzr branch fooFrom [fooTo]

The arguments are basically identical to those for checkout.

Unlike checkout, this is intended to create an extended history that forks from the original.

Examination

status

Version status of files:

bzr status

log

Revision log:

bzr log [files...]

diff

Compare current to last committed:

bzr diff [files...]

Compare a file between revisions 1 and 3:

bzr diff -r1..3 [files...]

info

Branch information:

bzr info

cat

Get the contents of a file (optionally from revision 3):

bzr cat [-r3] file > foo-file.out

Version ops

add

Add files to set of versioned files:

bzr add [--dry-run] [--no-recurse] [files...]

Any directories are traversed unless --no-recurse. --dry-run will list what would be added without doing the adding. If no files are given, . (current dir) is assumed.

rm

Remove files from set of versioned files:

# rm = remove = del
bzr rm [--keep | --force] [files...]

By default bzr will delete the files iff they can be recovered trivially with revert. --keep removes the file from versioning but leaves the working copy. --force removes the file from versioning and the working copy even if it is nontrivial to recover.

ci

Check a revision of files into the repository:

# ci = commit = checkin
bzr ci [files...] [-m message]

If files is omitted, the entire tree is used. If -m is omitted, your default editor is used to record the revision message.

uncommit

If the last commit was a mistake (and optionally the last non-mistake was revision 3):

bzr uncommit [location] [-r3]

revert

To revert files to the last committed revision (or optionally to revision 3):

bzr revert [files...] [-r3]

Files edited manually are backed up with a tail first.

Merging

merge

Merging works by attempting to apply changes that were made to another branch to the current working tree.

bzr merge ../foo.dev.branch

pull

To copy changes from another (non-divergent) branch, making this a mirror of that:

bzr pull fooFrom

up

To merge back the most recently committed code to this working copy:

# up = update
bzr up

resolve

Merges, updates, and so forth result in marked conflicts. After conflicts are resolved manually:

bzr resolve [files...]

If no files are given, bzr will try to automatically figure out what has been resolved. It may or may not succeed.

Publishing

push

To copy changes from this working tree to another (non-divergent) branch:

bzr push fooTo

send

To e-mail (or optionally just create) a merge directive (an archive that contains a series of revision changes):

bzr send [-o ../foo-updates.patch]

export

Exporting produces a snapshot of the To export the current revision (or optionally revision 3) to another file or directory:

bzr export [-r3] ../fooOut [branch|subdir]

If fooOut has an extension like .tar, .tar.bz2, or .zip, the destination will be an archive file of the suggested type. Otherwise, the destination will be a directory. (Use the --format option to override.)

Install a plugin

As described elsewhere, the general rule is to find the thing on Launchpad and branch it into your local plugins, stripping the bzr- prefix and substituting _ for -.

In general

cd ~/.bazaar/plugins &&
bzr branch lp:bzr-example-plug example_plug

Install bzr-git

cd ~/.bazaar/plugins &&
bzr branch lp:bzr-git git

But note that dulwich must also be installed.

# If you don't have easy_install or pip yet, this installs easy_install to a user-local path
# In the case of my cygwin, it was ~/.local/bin/easy_install
wget https://bootstrap.pypa.io/ez_setup.py -O - | python - --user

easy_install dulwich==0.9.1
# or pip install dulwich==0.9.1

Using bzr with github

Feel like you're missing out on the whole forking social development thing? Like markdown a whole lot and frustrated that Launchpad doesn't use it? Here's how to share code with a zillion of your friends without converting them.

Before proceeding, ensure that you're up on your SSH keys/credentials for github.

Caveats

Hangs

See #When Github gets sticky.

Submodules

No submodules yet. You'll have to learn git for that.

The URL

Previously, a more detailed translation of the repo URL was needed, but the current version of bzr-git allows almost the same format as git itself.

Get the SSH URL of the desired repo. It looks like this:

git@github.com:someuser/somerepo.git

You need to add a branch qualifier to the end (unlike in git, in bzr a working copy corresponds to exactly one branch). Suffix the URL with ,branch=master, replacing master with the desired branch name. The result is

git@github.com:someuser/somerepo.git,branch=master

Internally, this URL is normalized to bzr's own form, which resembles the following:

git+ssh://git@github.com/someuser/somerepo.git,branch=master

Exists on local, new on github

If the bzr branch you want to use already exists locally, create the new repo on github and be sure "Initialize this repository with a README" is unchecked. If it doesn't exist locally and you create the repo on github with a README, follow the #Exists_on_github advice instead.

From the root of the local bzr branch, do:

bzr dpush --remember URL

using master as the branch name.

If this worked, your content has been pushed.

Branch

Do

bzr branch URL somerepo

If the somerepo parameter is omitted, the name of the destination is the name of the git branch.

Pushing

Use dpush where you'd normally use push. This indicates that the push targets a non-bzr repo.

Pushing a new branch

Use dpush but also provide a URL qualified with the new branch's name. Use --remember to mark the URL as the new parent.

bzr --remember git@github.com:someuser/somerepo.git,branch=new-branch-name

When Github gets sticky

It seems as though Github works differently enough from normal git that some (or all) bzr-git commands do most of their job, then hang (for about 10 minutes, I estimate) before successfully completing. They usually do complete eventually, but you don't have time for this nonsense. Here are my workarounds:

dpush (to an existing or new branch)

If it's a dpush, in my experience you can get away with getting it up to the hanging point and then terminating bzr. Use the website to ensure that the changes were uploaded correctly.

Branching

This has historically worked for me without hanging, but today I'm having difficulties. Here's how to work around it with git.

Go to a temporary directory and clone the git repository. Make sure to include the --branch parameter to get the correct branch.

cd $TEMP
git clone --branch branch-name git@github.com:someuser/somerepo.git
# The clone is at $TEMP/somerepo

Then, go to where you want the project directory to appear and branch from the clone with bzr.

cd $PROJECTS

# If the last argument is omitted here, the new directory has the name of
# the branch, not the name of the project; this isn't usually what I want.
bzr branch $TEMP/somerepo branch-dir-name

# The bzr branch is now at $PROJECTS/branch-dir-name

Finally, go to the bzr branch and do bzr pull --remember to overwrite the parent URL. This doesn't hang (probably because there are no updates to pull).

cd branch-dir-name
bzr pull --remember git@github.com:someuser/somerepo.git,branch=branch-name

See

• Bazaar docs
• Bazaar project