Bazaar is a distributed VCS written in python. It offers both drop-in CVS replacement work flow (use checkouts to work on code), and full distributed work flow (every copy is a new branch), up to the user to work as they want.
- Repository Location
- Web view
- Let bzr know who you are
- Tell bzr where to find the Squid bugzilla
- Setup a mirror/development environment
- Create local repository
- Checkout an existing branch
- Make a new child branch to hack on
- Share the branch with others:
- bring a branch up to date with its ancestor
- Verify branch connectivity
- Submit a patch for inclusion in the main tree or discussion
- Commit directly to trunk
- cherry pick something back to an older release using CVS
- Merge another branch into yours
- diffing against arbitrary revisions/branches
- Helper scripts
Back to DeveloperResources
Bazaar is available in most O/S's these days: http://bazaar-vcs.org/Download.
Things to install (as a user):
- version 1.2 or later recommended for best performance, but 1.0 or later is sufficient.
- bzr-email (as a package it may be a bit old, try:
mkdir -p ~/.bazaar/plugins/ && bzr branch http://bazaar.launchpad.net/~bzr/bzr-email/trunk/ ~/.bazaar/plugins/email Then do 'bzr help email' and setup any local machine configuration you need in bazaar.conf - such as mailer to use etc.
- bzrtools (optional)
- adds the cbranch plugin, making it easier to work with a local repository
For anonymous access/mirroring/etc:
Also mirrors are available at:
Repository Developer branches
Let bzr know who you are
bzr needs to know your identity. A bzr identity is your name & email address.
bzr whoami "Your Fullname <firstname.lastname@example.org>"
or to verify what bzr thinks your identity is
If you don't do this bzr guesses based on your account and compuer name.
Tell bzr where to find the Squid bugzilla
add the following in $HOME/.bazaar/bazaar.conf [DEFAULT] section
bugzilla_squid_url = http://bugs.squid-cache.org
This enables bzr commit --fixes squid:<bugnumber> to mark bugs as fixed
Setup a mirror/development environment
The following sections will describe how to set up your local repository for Squid development. Two options are shown, differing in where the local repository is:
- plain method
- The bazaar repository is in the root of your Squid source tree.
- cbranch method
- The local bazaar repository is somewhere else in your filesystem, separate from where you do development. Easier to back up and branches are persistent in the repository even if you should happen to delete a whole source tree intentionally or by accident. Which means you can easily recover a branch after you have deleted the source tree.
Create local repository
# create a local repository to store branches in bzr init-repo --2a --no-trees ~/squid-repo # Create a place where to keep working trees mkdir -p ~/source/squid # Configure ~/.bazaar/locations.conf mapping the working trees to your repository cat >> ~/.bazaar/locations.conf << EOF [/home/USER/source/squid] cbranch_target=/home/USER/squid-repo cbranch_target:policy = appendpath [/home/USER/source/squid/trunk] public_branch = http://bzr.squid-cache.org/bzr/squid3/trunk/ EOF
Upgrade an old local repository
Squid-3 repositories have been upgraded to 2a format in September 2012. When using a local repository or branch checkout from prior to that period you may encounter repository format errors when using bzr.
The following upgrade procedures are recommended:
# upgrade the local repository format (takes approx 30-90 minutes) bzr upgrade --2a
Checkout an existing branch
After your setup is done its time to checkout the first branch you are going to work on directly, or create a child branch for. In most cases this will be the trunk branch.
cd ~/source/squid bzr cbranch --lightweight http://bzr.squid-cache.org/bzr/squid3/trunk trunk # bind the local copy of trunk to the official copy # so that it can be used to commit merges to trunk and activate the 'update' command cd trunk bzr bind http://bzr.squid-cache.org/bzr/squid3/trunk
cd ~/source/squid bzr checkout http://bzr.squid-cache.org/bzr/squid3/trunk trunk
If you have commit access to trunk use bzr+ssh://USERNAME@bzr.squid-cache.org/bzr/squid3/trunk instead of http://...
Make a new child branch to hack on
First follow the instructions above to setup a development environment
Now, in the below example, replace SOURCE with the branch you want your new branch based on, and NAME with the name you want your new branch to have in the following:
cd ~/source/squid bzr cbranch --lightweight ~/squid-repo/trunk NAME cd NAME bzr merge --remember ~/squid-repo/trunk
Share the branch with others:
you want to share (read-only) the branch with others also do:
cd NAME bzr push --remember PUBLIC_URL
e.g. if you were to use the launchpad.net bzr hosting service:
bzr push --remember bzr+ssh://bazaar.launchpad.net/~USER/squid/NAME
to update the shared copy in the future all you need to run is
bring a branch up to date with its ancestor
First update your copy of the ancestor;
cd ~/source/squid/trunk bzr update
Then merge the changes into your child branch:
cd ../NAME bzr merge [fix conflicts if any] bzr commit -m "Merge from trunk"
Then continue hacking on your branch.
If bzr merge complains on not having a source to merge from then use the following merge command once
bzr merge --remember ~/squid-repo/trunk
Verify branch connectivity
If bzr update in the ancestor branch runs very quick and doesn't seem to bring in any updates then verify that the branch is properly bound to the main repository location, not only having it as parent. "bzr info" should report something like the following:
Lightweight checkout (format: dirstate or dirstate-tags or pack-0.92 or rich-root or rich-root-pack) Location: light checkout root: . repository checkout root: /home/henrik/squid-repo/squid3/trunk checkout of branch: bzr+ssh://bzr.squid-cache.org/bzr/squid3/trunk/ shared repository: /home/henrik/squid-repo/squid3 Related branches: parent branch: bzr+ssh://bzr.squid-cache.org/bzr/squid3/trunk/
If "checkout of branch" is missing or indicates your local repository instead of the main source then you need to bind the tree. But first verify that you really are in the main working tree and not your own branch..
bzr bind bzr+ssh://bzr.squid-cache.org/bzr/squid3/trunk/
Submit a patch for inclusion in the main tree or discussion
Verify the contents of your branch
bzr diff -r submit: | less
If it looks fine then generate a diff bundle:
bzr diff -r submit: > your-patch-name.diff
Edit the file, add a preamble to the beginning of it stating its purpose, and email to the squid-dev mailing list (email@example.com).
You can use the following commands to email the patch directly, but they skip the step of adding a preamble.
bzr send --firstname.lastname@example.org
bzr send -oYourFeatureName.merge
It's also possible to cherrypick what to send using the -r option. See bzr help revisionspec for details
Commit directly to trunk
Make sure you have a clean up to date trunk tree:
cd ~/squid/source/trunk bzr status bzr update
bzr status should show nothing. If it shows something:
If you are merging a development branch:
cd ~/squid/source/trunk bzr merge ~/squid/source/childbranchFOO bzr commit -m "Merge feature FOO"
If you are applying a plain patch from somewhere:
cd ~/squid/source/trunk bzr patch PATCHFILE_OR_URL bzr commit # edit the commit message
If you are back/forward porting a specific change:
cd ~/squid/source/trunk bzr merge -c REVNO OTHERBRANCH_URL bzr commit # edit the commit message
cherry pick something back to an older release using CVS
Generate a diff using bzr:
bzr diff -r FROMREVNO..TOREVNO > patchfile
or if its a single commit
bzr diff -c COMMITREVNO > patchfile
and apply that to cvs with patch:
patch -p0 <patchfile
Merge another branch into yours
You can merge in arbitrary patterns, though because bzr 1.0 defaults to 'merge3' for conflict resolution the best results occur if a hub-and-spoke system is used where each branch only merges from one other branch, except when changes from a 'child' branch are completed and being merged into that branch.
cd ~/squid/source/DESTINATION bzr merge ~/squid/source/SOURCE_OF_FOO bzr commit -m "Merge feature FOO"
NP: The DESTINATION branch must be a local checkout of files to patch. The SOURCE branch may be the folder, bundle, or online URL of another branch.
diffing against arbitrary revisions/branches
To diff against a different branch there are several options. The most common and most useful one is 'ancestor' and will give you the diff since the most recent merge of that other branch. If there is a third branch that has been merged into both your branch and the one you are diffing, it's changes will appear in the diff. There is work underway to provide diffs that handle any merge pattern more gracefully - see merge-preview as the start of the work in bzr.
cd MYBRANCH bzr diff -r ancestor:URL_OF_OTHER_BRANCH
Another useful option is to diff against the current tip of a branch, which will show things that you have not merged from that branch as 'removed' and things you have created locally as 'added':
cd MYBRANCH bzr diff -r branch:URL_OF_OTHER_BRANCH
You can also diff against arbitrary revnos in the other branch:
cd MYBRANCH bzr diff -r 34:URL_OF_OTHER_BRANCH
For more information:
bzr help revisionspec
While bzr provides simple operation access. So did CVS in most cases. The problem is, mistakes are easier too. We need to provide some recipes as easy to use scripts.
- cleaning up a branch or patch for auditing
- testing a branch before submission
./test-builds.sh in squid source. Runs configure and build permutation tests.