How to use Bazaar

We're keeping all the code of the RCL site under version control in Bazaar so we can reverse any bad changes we make and keep our changes synchronized with each other. Here's how to use Bazaar.

Key Concept: Distributed Version Control = TWO Repositories

Bazaar is a Version Control System like Subversion and CVS, but it does not require that you use one central repository like Subversion and CVS.

  • Central repository: You can use it with a central repository by using the following command sequence: bzr checkout, bzr update, [edit code], bzr add, bzr commit. In this case all commits go directly into the central repository. This is the way CVS & Subversion work.
  • Central & Local = Distributed repositories: But we're going to use it with a central repository we'll call the "mainline" (which is the "trunk" branch of RCL on Launchpad), and one "distributed" repository per developer which we'll call your "local branch." The advantage is that you can track and test revisions locally, and if necessary roll them back, before committing them to the mainline repository shared with other developers (see also WhyDevelopLocally). You follow the same general workflow and command sequence as above, except that instead of committing your changes directly to the mainline, you first commit them to your local branch (your local repository), and then you sync your local branch's changes to the mainline repository. This two-stage process can confuse you if you're unfamiliar with it. The KEY is to remember you have TWO repositories--the central mainline and the local branch. So your workflow goes like this:
    • Get from mainline: bzr branch [or pull]
    • Update local working tree from local branch: bzr update, [edit code]
    • Add any newly created files to the pending commit: bzr add
    • Commit(s) to local branch: bzr commit
    • Merge changes to mainline branch: bzr push [or merge]
    • On mainline branch's filesystem's commandline (so log in via SSH), commit merged revisions to mainline repository: resolve conflicts, bzr commit

TIP: If you're not sure what stage of the workflow you're in, type bzr status, and if you don't know what command to use, type bzr help.

Wrinkle: Production/live & development/testing sites

Initially our work will be in local branches and the "trunk" branch on Launchpad alone. But eventually we will also use two branches on 1) the production/live site, and 2) the development/testing site. Please try to do most of your development in your local branch if possible, though, to keep from cluttering the development site with multiple developers' unfinished work. After completing your work in your local branch, you can merge your changes into either the development/testing branch/site (if you think it's wise to test on the production server first) or directly to the production branch (if you're pretty sure no testing is needed.) You'll also find some work (e.g., testing email notifications) just can't be done in a local copy of the site, and so has to be done in the development/testing branch on the production server.



  • On Linux it's not hard to use the command line for everything, or at least for checkout and pushing to the mainline. For a GUI, try Bazaar Explorer or Ground Control. See Bzr and SSH for how to upload your public key to your remote ~/.ssh folder, and HowToUseSSH for help logging into the production & test server.

Cheat Sheet

General workflow


  • If (you're beginning to work on the live or test sites and) you haven't done so yet, create links to the Bazaar installation directories in your home directory on the Webfaction server so it is available in your path:
    cd ~
    ln -s /home2/timblack1/bin
    ln -s /home2/timblack1/lib
  • Identify yourself to Bazaar (so we know who made each changeset):
    bzr whoami "Frank Chu <>"
  • I intend for us to use the Decentralized with shared mainline workflow.
    • The RCL trunk on Launchpad serves as the shared mainline, and is at lp:reformedchurcheslocator.
  • So, to get started with development:
    • BRANCH: in an empty directory on your computer, check out a branched repository off of the mainline repository using the following command, replacing "your_username" before the @ with your SFTP username:
      bzr branch lp:reformedchurcheslocator
    • CHECKOUT: If necessary, type your SSH/SFTP password, then if bzr branch didn't create a local working tree, checkout a working copy from your local repository:
      bzr checkout
    • DEVELOPMENT: Make your changes to the code, then type the following as needed (explanations are in the comments):
      bzr pull # from mainline; bzr merge may be necessary
      bzr add # to local repository
      bzr commit # to local repository
      bzr push lp:reformedchurcheslocator # pushes to mainline; bzr merge may be necessary
      bzr update # in mainline
    • DEPLOYMENT: Normally you'll deploy tested changes directly to the production site (see also WhyDevelopLocally). But you'll need to deploy changes to the development site in order to test & fix them in the following situations:
      • when your changes don't work on the production site
      • when your changes can't be tested locally. E.g., testing email-related features
      • when your changes are difficult to roll back. E.g., changes to the database


  • Uncommitted Changes: If you make changes directly on the production or development server then from your local Bazaar repository try to bzr pull, bzr push, or bzr merge (all actions which access the main repository), bzr may complain that there are uncommitted changes in the working tree on the server. So, you have to commit or revert those changes in the server's working tree before you can push your local commits in. Then it works.
Last modified 6 years ago Last modified on 07/23/12 22:19:14