Simplified Tutorial

Fri May 5 21:00:12 BST 2006

This is really nice, Erik. A couple of small nits:

On Fri, May 05, 2006 at 09:18:08PM +0200, Erik Bgfors wrote:
> 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.

"store"?

> By putting the branches in a shared repository, they will use the same
> storage for things that are the same between different branches.  It

Idem.

> 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

s/support/supports/

> 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

Note that this assumes that ssh-agent is running and accessible from the
shell.

> 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

Maybe explain that ssh-copy-id appends the public key to
server:~bzr/.ssh/authorized_keys?

> 
> 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.'

s/cvs/bzr/

> 
> 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.

-- 
Jos Backus
jos at catnook.com