Bazaar is a version control system, much like Subversion or the ancient CVS. The advantage of Bazaar is that it lets you make your own “branch” of the code, where you can make and undo changes while not interfering with anyone else’s code, but you can also stay up to date with the main “trunk” of the code.
The official Bazaar documentation is actually quite good, but we’ve made this document as a shorter summary of the things we found we needed. Feel free to suggest more things!
Install Bazaar (http://bazaar-vcs.org/) or on Ubuntu:
sudo aptitude install bzr
Sign up for Launchpad (http://launchpad.net/)
Join the Commonsense Computing team (http://launchpad.net/~commonsense)
Register an SSH public key with Launchpad:
Tell Bazaar about your Launchpad id:
bzr launchpad-login myusername
Start by making a branch of the project you’re working on:
bzr branch lp:conceptnet my_conceptnet_branch
(This gives you a local working directory called my_conceptnet_branch.)
Hack vigorously...
If you create new files, add them:
bzr add filename
Commit often, usually for every major step you take (you’ll be glad later):
bzr status # make sure there's no new files you meant to add
bzr commit -m "this is my highly informative commit message"
This commits to your version-controlled repository. It can’t mess with anyone else. It’s safe.
When new things happen on the trunk, you can get your branch up to date by pulling those changes:
bzr pull lp:conceptnet
However, if you’ve committed things to your branch, you have to merge the upstream changes with your own:
bzr merge lp:conceptnet # get your branch up to date with what's changed
bzr commit -m "Merged"
When it’s ready for prime time, push it back into the trunk:
bzr push lp:conceptnet
If the trunk has changes you haven’t merged, you’ll need to merge before you can push.
Okay. This makes perfect sense for a quick change, but if you make a habit of this you’re probably going to get in someone’s way.
Instead of branching, get a checkout:
bzr checkout lp:conceptnet
A checkout is a working copy whose repository is somewhere else. When you commit, it commits to that repository. This is how everything worked in Subversion.
To pull in new stuff from the repository:
bzr update
To commit your changes to the repository:
bzr commit -m "extremely informative message"
You’ve made a branch on one computer, and you want to work with the same branch on another computer. No problem. Make a checkout of it:
bzr checkout bzr+ssh://your.host.name/path/to/your/branch
Now you have multiple checkouts of the same branch, and you can update, commit, etc. just like above.
This also makes sense if you want to work on some minor branch that’s on Launchpad (like lp:~commonsense/conceptnet/new-caledonia) without re-branching it. Check out that branch and commit to it.
Are you doing cool stuff that we want to see, but isn’t ready to go into the trunk? You can host your branch on Launchpad where others can see it. Here’s how to do that:
bzr push lp:~username/project/branch-name
For example, Rob might do this:
bzr push lp:~rspeer/conceptnet/speed-up-the-lemmatizer
That’s right, you can just make up a URL like that and suddenly Launchpad is hosting a branch for you. Now “bind” your branch to that new hosted branch:
bzr bind lp:~username/project/branch-name
The bzr bind command means that your directory becomes a checkout instead of a branch; when you commit or update, you will do so by talking to Launchpad. It’s slower, but now your code is accessible from anywhere (and backed up, too).
If you committed something you didn’t mean to, you can fix it:
bzr uncommit
(This does work even on a checkout of a remote branch, but if anyone has pulled from it since you committed, they might not be happy with you. Honestly I haven’t tried it.)
If you added something you meant to be unversioned:
bzr remove --keep filename
If you want to go back to a previous revision, look up how to use bzr revert -r to revert to an earlier revision.
If you pushed to somewhere you didn’t mean to, check out that branch and revert it back to something sane.