.. This tutorial is written in ReStructuredText_ format, which can be converted into html using ``rst2html``. The preferred command is ``rst2html --stylesheet=default.css --link-stylesheet simple_tutorial.txt simple_tutorial.html`` .. _ReStructuredText: http://docutils.sourceforge.net/rst.html ========================= Bazaar-NG Simple Tutorial ========================= A simplified step-by-step tutorial for Bazaar-NG. How to read this tutorial ========================= Command names and parameters are displayed in ``fixed font``. A line of input that you should type into your command prompt is given in a separate box, and starts with a ``%`` character. The output of the command follows it, without the beginning ``%``.:: % this is an input line This is the output Examples are given expecting the user to be using ``bash`` as the shell. Where other shells (such as Windows ``cmd.exe``) differ, should be noted. Installation ============ This section describes how to install ``bzr`` and get up and running. I will let someone else fill in the details here See the online Installation_ guide. .. _Installation: http://bazaar-vcs.org/Installation Bazaar-NG installs a single new command, ``bzr``. Everything else is a subcommand of this. You can get some basic help with ``bzr help``.:: % bzr help Bazaar-NG -- a free distributed version-control tool http://bazaar-ng.org/ Basic commands: bzr init makes this directory a versioned branch bzr branch make a copy of another branch ... bzr help init more help on e.g. command init bzr help commands list all commands To determine what version of ``bzr`` you are using, you can use:: % bzr --version bzr (bazaar-ng) 0.8rc1 bzr checkout, revision 1701 nick: bzr.dev revid: pqm@pqm.ubuntu.com-20060505082929-a037ee137f1ff240 Copyright 2005,06 Canonical Development Ltd. http://bazaar-ng.org/ bzr comes with ABSOLUTELY NO WARRANTY. bzr is free software, and you may use, modify and redistribute it under the terms of the GNU General Public License version 2 or later. Don't worry about things like ``revid`` just yet. But it will help Bazaar developers know exactly what version of ``bzr`` you are running. Introducing yourself to Bazaar-NG --------------------------------- One function of a version control system is to keep track of who changed what. Bzr uses an email address since these are common and generally unique. Bzr is tries to guess your email address by looking up your username and hostname. You can use ``bzr whoami`` to check:: % bzr whomai John Arbash Meinel If this is not accurate, you can set the username using one of these two methods. 1. Set the email address in ``~/.bazaar/bazaar.conf`` by adding the following lines. Please note that ``[DEFAULT]`` is case sensitive:: [DEFAULT] email= Your Name 2. Setting the global environment variable ``$BZREMAIL`` or ``$EMAIL`` (``$BZREMAIL`` will take precedence) to "Your Name ". :: % export BZREMAIL='Joe Foo ' % bzr whoami Joe Foo % unset BZREMAIL Bzr also supports setting a separate email address for each branch. For more details, see BzrSettingEmail_. .. Consider mentioning that you would use 'set BZREMAIL=foo' on windows and csh style shells (or is it setenv?) .. _BzrSettingEmail: http://bazaar-vcs.org/BzrSettingEmail Bzr Structure ============= .. I tried to make a simple diagram of the structure. But this could *easily* be too much information at this point Bzr uses a layered structure to allow flexibility in how it is used. So lets define a couple terms: * Working Tree: This is where all of *your* files reside. * Branch: A branch maintains the concept of history. It tracks what changes have been committed and merged into your tree. * Repository: This is where all the history actually resides. Now that we understand how bzr splits things up, how does it put them back together: * Standalone Branch: This is an all-in-one location. In a standalone branch, everything resides underneath the same ``.bzr/`` directory. Most DRCS systems (darcs, mercurial, git, bitkeeper) use something similar to standalone branches. This is one of the most common forms of branches, and is recommended for small projects that don't have a lot of branching. With a standalone branch changes are committed locally, and must be published for other users to see them. * Checkout: A checkout is similar to a Standalone Branch, in that it contains the history information, and a working tree to make changes. The primary difference is that a Checkout is linked (bound) to another branch, such that committing to the checkout also commits the changes to the remote branch. Also, if people are sharing the remote branch, it will require you update your local branch before you can commit. This is very similar to how centralized systems (cvs, svn) work, with the added benefit that you can easily switch between a checkout and a standalone branch (``bzr bind``, ``bzr unbind``) for situations like taking your laptop on an airplane. * Light Checkout: This takes the concept of a checkout one step further, and removes the local history entirely. This results in a situation very similar to CVS, where you *must* contact the remote location in order to perform operations (``commit``, ``annotate``, ``status``). The primary advantage is that it does not need to download the history data when creating a new checkout. * Repository Branch: With Bzr it is possible to have branches share their history data. This is especially useful for projects that create lots of branches (such as short-lived feature branches). This is done by creating a Repository (``bzr init-repo``). Future branches that are created in subdirectories will all store their historical information in the same location. Merging between branches that share the same repository is very fast, since no information needs to be copied. Best Practices ============== A small collection of recommendations usage of bzr. Using Repositories ------------------ Create a remote repository for archiving and sharing your branches, and a local repository to reduce the need to copy information around. Bind the local branches to the remote branches, so that changes get published without extra work. The 'remote' repository doesn't actually need to be on another machine, but for most people it will be. Setup the shared location, this can be on a local or remote machine :: % ssh other-host % cd /public/place % bzr init-repo repository % exit Create a local repository in ~/dev. The ``--trees` flag says that branches created here should have Working Trees. :: % cd ~/ % bzr init-repo --trees dev % cd dev Create a new local branch from some existing tree :: % mkdir myproject % cd myproject % cp -ar ~/old/project/location % bzr init % bzr add % bzr commit -m "Starting the new project" Publish this branch in the remote repository, and bind to it. .. In the future, this should probably use 'bzr branch' not push :: % bzr push sftp://other-host/public/place/repository/myproject/ % bzr bind sftp://other-host/public/place/repository/myproject/ At this point, any changes that you commit to your local project, should show up on the other host. Feature Branches ---------------- Now when you start making a change, you can create a cheap feature branch, which keeps changes cleaner and more isolated. Create a feature branch, publish it, and bind it :: % cd ~/dev/ % bzr branch myproject myproject-feature % cd myproject-feature % bzr push sftp://other-host/public/place/repository/myproject-feature/ % bzr bind sftp://other-host/public/place/repository/myproject-feature/ .. vim: ft=rst