~bzr-pqm/bzr/bzr.dev

******************************

Learn Bazaar in twenty minutes

******************************

:Author:

  Martin Pool <mbp@sourcefrog.net>

:Date: November 2004, London

*Bazaar* is an open source distributed version control system.  A

version control system helps you develop software (or other documents)

In Bazaar, branches hold a history of their changes.  All working

copies are branches, and all branches are working copies.

Let's get a copy of someone else's published project::

    $ baz branch http://baz.alice.org/hello-2.6

This creates a directory called ``hello-2.6`` in your current

directory, containing Alice's *Hello World* 2.6 tree and a history of

her changes.  We'll leave this directory containing a pristine copy of

her work for future reference.

We want to add a new feature.  Branching and merging is are cheap and

easy in Baz, so development of each new feature should be done on a

new branch -- this lets you merge them in different orders, and leave

aside new development to fix a bug if you want.  It's good to choose a

meaningful name for your development branches so that you can keep

them straight.  So let's make an additional branch, based off our

local copy of Alice's branch::

    $ baz branch ./hello-2.6 ./hello-2.6-goodbye

This command completed quickly: we didn't need to fetch anything from

Alice's server to make a new branch.

Now we have a second directory containing another copy of the source,

with a different name.  Of course both are still the same as Alice's

source.  Time to hack::

    $ cd hello-2.6-goodbye

    $ vi hello.c

We add a new and much-desired ``--goodbye`` option, build and test

it.  Having got to a good state, we think we're ready to commit our

changes.  Many people find it helpful to review the changes before

committing them, just to make sure there were no accidental mistakes::

    $ baz diff | less

This shows the changes relative to the version we started with.  If

that looks OK, we're ready to commit::

    $ baz commit -m 'Add --goodbye option'

This records the changes into this branch.  We can see that they got

recorded::

    $ baz log | less

This will show our change as the most recent, preceded by all our

development.  If we only want to see our own changes, we can filter

the log in various ways::

    $ baz log --author bruce@ 

    $ baz log --date today 

(That second one might include anything Alice did before we started.)

Since our changes were committed, we don't have anything outstanding,

as we can see with this command::

    $ baz diff 

    No changes

Thinking about it a bit more, we decide that it's too messy to mix the

"Goodbye" implementation in with "Hello world".  We start up our

editor and split it our into a new separate file, ``bye.c``.  By

default, Baz assumes unknown files in the working directory are

scratch files -- the same behaviour as CVS and Subversion.  We need to

tell Baz that this file should be versioned, and then we can commit::

    $ baz add bye.c

    $ baz commit -s 'Refactor bye() into separate file'

Of course this commits all our changes as a single atomic

transaction.  If we wanted, we could tell Baz to build the program

before committing to help ensure we never get a broken build.

We're ready to publish our improved Hello World, but first we want to

make sure we've integrated anything Alice has done while we were

working.  First we update our mirror of Alice's branch::

    $ baz sync ../hello-2.6

This pulls the history of her branch onto our machine; we could

disconnect from the network at this point and do all the merging work

without needing to connect to ``alice.org``.   

Now we'll pull Alice's new changes into our branch.  We can use a

mirror of her branch, or we can go straight to her public branch.  In

fact, we can merge from different copies of the same branch at

different times, and Baz will still understand which changesets have

already been merged.  Either of these commands will work::

    $ baz merge ../hello-2.6

    $ baz merge http://baz.alice.org/hello-2.6

This pulls down any changesets on Alice's branch that aren't in ours,

and applies them to our tree.  Since we've made changes in parallel

with Alice, those changes might conflict.  Baz by default will insert

CVS-style conflict markers into your branch if that happens, but you

can also ask it to run a graphical merge tool or to tell emacs to do

the merge.  Baz will help you merge changes other than file text, such

as a file being renamed in one branch.  

By running ``baz diff`` we can see the effect of her changes on our

tree.  By running ``baz log --pending`` we can see a description of

all of the changes that were pulled in.  Once the changes have been

reconciled (which will often happen automatically), we can commit this

to our branch::

    $ baz commit -s 'Merge from Alice'

Baz records that our change incorporates those patches from Alice::

    $ baz log | less

Now that we have the feature we wanted, we can publish our branch on

the web.  We could copy it up using ``baz branch``, but because Baz

branches are simply directories we can just rsync it onto a web

server, even if the web server doesn't have Baz installed::

    $ rsync -av ./hello-2.6-goodbye webserver.com:public_html/

We send an email to Alice asking her to merge from this location.

Typically she'll want to have a look at those changes before accepting

them, and she can do that by running ``merge`` then ``diff``, as we

did before.  If she likes the change, she can merge it, possibly

applying some fixes in the process.  Next time we merge from her,

we'll see our changes are in.

.. Local variables:

.. mode: rst

.. compile-command: "rest2html short-demo.txt > short-demo.html"

.. End: