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].
Contents
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
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.
If it's a dpush, in my experience you can get away with getting it up to the hanging point and then terminating the process. Use the website to ensure that the changes were uploaded correctly.
For an initial pull or branch, you might just be stuck waiting. One workaround is to do the actual branching with git, use bzr to branch from the result of that, and then overwrite the parent location with the Github address. (See below.)
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.
Creating new github branches
If the branch doesn't exist on github yet, and you'd like to create it, theoretically dpush should work, but on my system it just hangs.
Here's how to do it with git itself.
First, get a light local git repo and set the origin. The URL is the same except the ,branch=... part is omitted.
mkdir somerepo cd somerepo git init git remote add origin URL-without-branch
Then, simply pull the branch of origin and push it back up with a new name.
OLDBRANCH=oldbranch && git pull origin "$OLDBRANCH" && git checkout "$OLDBRANCH" NEWBRANCH=newbranch && git checkout -b "$NEWBRANCH" && git push -u origin "$NEWBRANCH"
It might be worth making a script out of that.
If the same needs to be done more than once, only the part starting with the pull needs to be repeated.
