Bzr Intro
The Bzr Intro class should give a basic understanding of how to use the bzr revision control system and some of the useful helper utilities available for bzr.
background
prerequisites
- basic familiarity with commandline and Command Line 2
- familiarity with a text editor
suggested background
- basic understanding of cvs, subversion or other revision control systems
topics covered
help
short help message:
bzr help
get a list and short description of all commands:
bzr help commands
get help on COMMAND:
bzr help COMMAND bzr COMMAND -h
many commands have a short and long alias, help or -h will list them.
who am i
the first time you start working with bzr on a given machine, let it know who you are, so commit messages will have useful identifiers:
bzr whoami 'FOO BAR <FOO@example.com>'
starting a new project
bzr init PROJECT cd PROJECT bzr add FOO BAR BAZ bzr ci -m 'added initial files' bzr push --remember sftp://some.server/home/USERNAME/public_html/bzr/PROJECT/my-branch
working on an existing project
bzr get URL ORIGIN bzr get ORIGIN NEW_FEATURE cd NEW_FEATURE while feature_is_incomplete: hack, tweak, etc. bzr di bzr ci bzr push --remember sftp://some.server/home/USERNAME/public_html/bzr/PROJECT/NEW_FEATURE
announce that your branch has this cool new feature to the project mailing list or irc channel:
hey, just implemented a fix for bug #10: bzr get http://some.server/~USERNAME/bzr/PROJECT/NEW_FEATURE
staying in sync
after making lots of changes, and upstream made lots of changes, it's time to get back in sync with upstream:
bzr merge ../NEW_FEATURE bzr ci -m 'merged amazing new feature: NEW_FEATURE' bzr push sftp://some.server/home/USERNAME/public_html/bzr/PROJECT/my-branch
comparing revision history
get revision number of current branch:
bzr revno
get a log of revisions in current branch:
bzr log bzr log --short
get log of revision 5:
bzr log -r 5
get a short log of revisions between 5 and 9:
bzr log -r 5..9 --short
get log of the last two revisions:
bzr log -r -2..
compare revisions between OTHER_BRANCH and current branch:
bzr missing OTHER_BRANCH bzr missing --short OTHER_BRANCH
partial merging
merge everything up to and including revision 5:
bzr merge -r 5 SOME_BRANCH
merge changes introduced in revision 6, but not revisions 1-5:
bzr merge -r 5..6 SOME_BRANCH
checkouts
checkouts are very similar to branches, with one key difference- by default, they require access to the original branch in order to commit.
bzr co ORIGIN LOCAL_CHECKOUT cd LOCAL_CHECKOUT date > test bzr add test
make the ORIGIN branch inaccessible:
mv ../ORIGIN ../ORIGIN.borked
and then attempt a commit:
bzr ci
multiple users can commit to the same branch, making sure everyone has read and write permission to the branch directory.
it is recommended to use the --append-revisions-only flag when creating the branch:
bzr init --append-revisions-only /path/to/shared/repository
otherwise, pushes and pulls can change the revision history, which makes it harder to keep track of who changed what when.
using checkouts in combination with shared branches, you get behavior very similar to a centralized VCS, such as subversion.
optimization
to use a common storage space for all your revisions:
bzr init-repo PROJECT
any branches checked out under PROJECT will share revision information when possible.
bzr get URL1 PROJECT/FOO bzr get URL2 PROJECT/BAR
when you get the second branch, most of BAR is identical to FOO, so you only need to download the differences. highly recommended for publicly accessible branches.
tagging
in older versions, tagging was done merely by copying a branch to another location. this if you use the init-repo method to store your branches, this shares common revisions with other branches, so doesn't waste much space:
bzr push sftp://some.server/home/USERNAME/public_html/bzr/PROJECT/releases/FOO-1.2.3
with newer versions of bzr, you can use tags much like with cvs. it does require initializing the repository with a special format:
bzr init --dirstate-tags some-branch
if you forgot to do so, you can upgrade:
bzr upgrade --dirstate-tags .
then you can start making tags:
bzr tag SOME_TAG_NAME
tag revision 559 as with tag 1.2.3:
bzr tag -r 559 1.2.3
make a new branch from the tag 1.2.3:
bzr get -r tag:1.2.3 some-branch some-other-branch
converting an existing project from subversion or other vcs
with bzr-svn, it's rather simple:
bzr get SUBVERSION_URL PROJECT
it's also possible with tailor.
both claim to be able to continue to make commits on the subversion backend, but i have not actually tested how well tailor works in practice. bzr-svn seems to at least handle simple cases.
bzrtools
i make regular use of the shelf feature from bzrtools installed:
bzr shelve bzr unshelve bzr shelf ls bzr shelf show bzr shelf del
it allows you to set aside parts of revisions, even within individual files, to make it easier to commit only related changes.
http://doc.bazaar-vcs.org/latest/en/mini-tutorial/index.html