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
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
