Simplified Tutorial

[Erik Bågfors]

On 5/5/06, John Arbash Meinel <john at arbash-meinel.com> wrote:
> I've been playing around with simplifying the bzr tutorial. The one we
> have has a lot of great information, but I think it is a little bit too
> wordy. For people who just want a step-by-step to get up and running, I
> think we could strip out a lot of stuff.
>
> I've been sort of following Mercurial's tutorial, and the tutorial.txt file.
>
> Attached is a rough draft of a start at something more streamlined.
> I've also included a css style file. Which while not great, still looks
> a lot better than the default.

I love it, I played around for about 10 min with a "using bzr in a
centralized fashion for svn/cvs users"-tutorial.  The following is the
results, I'm not saying that this is good, but this is the way I
intend to get some svn/cvs-people to look at using bzr.

Some parts are taken from other documents (as you may see)

Here it is

=====================================================
Bazaar-NG Tutorial for centralized use (svn/cvs like)
=====================================================

Current for bzr-0.8, 2006-05


Introduction
============
This document describes how to use bzr in a way similar to cvs and
svn, where many developers has access to a central repository that
contains branches, and they work directly in this repository.

bzr can be used in this mode as well as in a decentralized way. 
Please refer to other documentation to learn how to use bzr in a
decentralized way.

For cvs/svn users this is normally the fastest way to get started.


Introduction to shared repositories and branches
================================================
A shared repository is a storage that can contain multiple branches.
By putting the branches in a shared repository, they will use the same
storage for things that are the same between different branches.  It
is recommended to keep related branches in a shared repository.

Branches in bzr can also be standalone, in this case, each branch does
not share the same storage.

The setup described in this document is where you have one centralized
shared repository on a central server. This repository is then used by
all developers.  In this setup, each developer needs to be able to
login to this central server.  Please note that bzr also support
decentralized usage where each developer does not need this access.

Preparing the central server
============================
On the central server, create a user that will be used for bzr, for
example **bzr**. Also define where to store the central repository, in
this tutorial, "/path/to/repo" will be used.

Make sure that the bzr user has read/write access to this path.


Setting up the developer machine
================================

The recommended way to use this repository, is that each developer
gets access to the "bzr" user at the central server. The simplest way
to do this, is that each developer creates a ssh-key and this ssh-key
is used to authenticate the developer.

If the developer does not have a ssh-key, On the developers machine, run
$ ssh-keygen -t dsa
to generate a key.

Then use
$ ssh-add
to "open" the key

Now the developer needs to make sure that this key is used to
authenticate as the bzr user at the central server. This is done with
the following command
$ ssh-copy-id bzr at server

After this is done, the developer should be able to login to the
server with the normal ssh command, without having to enter a
password.


The developer should then setup his/her bzr id.  The simplest way to
do that is to make sure that the following is in ~/.bazaar/bazaar.conf
    [DEFAULT]
    email             = John Doe <jdoe at isp.com>

See configuration.txt for more info.

Creating a centralized shared storage
=====================================
  $ bzr init-repo sftp://bzr@server/path/to/repo
to create the shared repository.

In this repository, you need to create a branch, this is done with the
command "bzr init", for example
  $ bzr init sftp://bzr@server/path/to/repo/branch
will create a branch named "branch" inside the repository.


Checking out the branch
=======================

The developer can then checkout the branch with

  $ bzr checkout sftp://bzr@server/path/to/repo/branch checkout

Updating a checkout
===================

In the CVS world you may have done a checkout. From time to time you
have to get new changes from the repository and apply them to your
checkout. This usually looks something like this:

 $ cd checkout/
 $ cvs update

This looks very similiar in the Bazaar-NG world:

 $ cd checkout/
 $ bzr update

In both the CVS and Bazaar-NG case this will mean that the changes in
the repository or branch that you do not yet have in the working tree
will be applied. You might have to deal with conflicts.

Seeing how a working tree has changed since the last commit
===========================================================

In the cvs world we often want to check how we have changed things
since we last committed. By checking how the code base has changed, we
can see what we're about to commit before we actually perform the
commit.

In the CVS world, we would check the changes this way:

 $ cvs -n update
 [see a list of files that have changed, or that need to be updated]
 $ cvs diff
 [see a diff of how files have changed]

This is very similar in Bazaar-NG:

 $ bzr status
 [see a list of files that have changed]
 $ bzr missing
 [see a list of new revisions in the parent branch]
 $ bzr diff
 [see a diff of how files have changed]

In both of these cases, you'll get a diff that you can review prior to commit.

(cvs also has a status command, but it's less useful and rarely used.)

Comitting code in a checkout
============================

In the CVS world you may have made changes to your checkout that need
to be saved in the repository. One typically does so in this way:

 $ cvs commit -m'some description of whats being committed.'

Again, this looks very similiar in the Bazaar-NG world:

 $ bzr commit -m'some description of whats being committed.'

In both of these cases, the new changes will be saved to the central server.


Working offline
===============

bzr gives you the possiblity to work offline, this is very simple. 
Just do your development like you normally do, then run

 $ cvs commit --local -m'some description of whats being committed.'

This will commit the changes on the local machine only.  You can do as
many commits as you like.

When you are back online, you want to make sure that these commits are
put into the central branch.  Since other developers can have been
commiting other things to the central branch, you need to merge your
changes in.  This is done by running the normal "bzr update" command. 
After you run it, you will see that your changes are put aside and are
viewable with "bzr status"

 $ bzr status
 pending merges:
  John Doe 2006-05-05 local commit 2
    John Doe 2006-05-05 local commit 1

There is now a chance that there are conflicts that has to be solved. 
This is done by editing each file that has conflicts, resolving them,
and then running
 $ bzr resolve path/to/file

You can see all files that has conflicts with the "bzr status" command.

After all conflicts are resolved, you can commit your changes to the
central server with

$ bzr commit -m 'my local changes'

If you run "bzr log" now, you will see something like this

------------------------------------------------------------
revno: 3
committer: John Doe <jdoe at isp.com>
branch nick: branch
timestamp: Fri 2006-05-05 16:53:04 +0200
message:
  my local changes
    ------------------------------------------------------------
    merged: jdoe at isp.com-20060505144747-1ace4aec2f21c564
    committer: John Doe <jdoe at isp.com>
    branch nick: branch
    timestamp: Fri 2006-05-05 16:47:47 +0200
    message:
      local commit 2
    ------------------------------------------------------------
    merged: jdoe at isp.com-20060505144745-818c3de13b8e4df0
    committer: John Doe <jdoe at isp.com>
    branch nick: branch
    timestamp: Fri 2006-05-05 16:47:45 +0200
    message:
      local commit 1

As you can see, the local changes has been merged into the central branch

Please note that most bzr commands (log, diff, status, etc) work just
fine even if you are working offline.

Creating branches in the central shared repository
==================================================

Within the shared repository it's cheap to create new branches.  To
create a new branch, go to your checkout and run
 $ bzr push sftp://bzr@server/path/to/repo/newbranch

This branch can then be checked out with
 $ cd ..
 $ bzr checkout sftp://bzr@server/path/to/repo/newbranch newbranch-checkout

like before

Please note that the following command doesn't work yet, it will in the future
 $ bzr branch sftp://bzr@server/path/to/repo/branch
sftp://bzr@server/path/to/repo/newbranch

Inside the repository, the branches can be arranged in any way you see
fit, if you are comming from the svn world, it's possible to keep the
trunk/branches/tags setup that you are used to.