This is a mini-tutorial for installing and using bzr on your mentor
home directory.  bzr is a simple free distributed version control
system (http://bazaar-vcs.org/) that is often considered easier to use
than CVS.

Disclaimer :: I take no responsibility for any damage (real or
perceived) caused to any machine as the result of following these
instructions, nor for time lost by following these directions.

<contents>

* Prerequisites

 1. Have the ssh daemon installed on your work machine.  In
    particular, sftp support must be enabled.  This is the default
    with most installations.

 2. Know your IP address or hostname.  This implies that you are on a
    machine with its own externally-resolvable IP address.  This will
    probably be the case for most of you.  We will call this piece of
    information =$HOST= in the instructions.

 3. Add =/usr/local/bin= and =~/bin= to your =PATH=.  You will have to log
    out and log back in for these changes to take effect.

    For bash, this involves editing (or creating) =~/.bash_profile= and
    adding the following line to it.

    <example>
    export PATH=~/bin:/usr/local/bin:$PATH
    </example>

    For tcsh, this will involve adding the following line to your
    =~/.cshrc=, as far as I can tell.

    <example>
    set PATH=~/bin:/usr/local/bin:$PATH
    </example>

* Installing bzr on mentor

Note: "\" at the end of a line indicates a line continuation; you can
safely type it and hit Enter, or you can type the next line on the
same line as the first, omitting the "\".

First, ssh into mentor.

Then, run the following commands.

<example>
mkdir src
cd src
GET http://bazaar-vcs.org/pkg/bzr-0.9.tar.gz | gzip -dc - | tar xvf -
GET http://effbot.org/downloads/elementtree-1.2.6-20050316.tar.gz \
  | gzip -dc - | tar xvf -
GET http://www.lag.net/paramiko/download/paramiko-1.6.2.tar.gz \
  | gzip -dc - | tar xvf -
GET http://www.amk.ca/files/python/crypto/pycrypto-2.0.1.tar.gz \
  | gzip -dc - | tar xvf -
cd pycrypto-2.0.1 ; python setup.py install --home ~ ; cd ..
cd paramiko-1.6.2 ; python setup.py install --home ~ ; cd ..
cd elementtree-1.2.6-20050316 ; python setup.py install \
  --home ~ ; cd ..
cd bzr-0.9 ; python setup.py install --home ~ ; cd ..
</example>

At this time, run =bzr --version=.  You should see the text "bzr
(bazaar-ng) 0.9.0" on the first line.

* Installing bzr on your work machine

I will defer to the official bzr website at http://bazaar-vcs.org/.

* Transferring your work directory to mentor

On your work machine, get and unpack the lab1-src.tar.gz file
according to the instructions at
http://www.cs.purdue.edu/homes/cs354/lab1/.  Make sure that this is
not in a publicly-accessible directory, such as a website.

Initialize your working directory for Lab 1.

<example>
cd lab1-src
bzr init
bzr add .
bzr commit -m "Initial contents of lab 1"
</example>

After completing the previous instruction, you should see "Committed
revision 1." at the end of the output.

Now, ssh into mentor, and we will retrieve your working directory from
your work machine.  Replace =$REMOTELAB= with the location where your
CS354 labs are stored on mentor.  Replace =$WORKLAB= with the location
where your labs are stored on your work machine -- it should be the
full path, not relative to your home directory.  Also, replace =$NAME=
with your login name on your work machine.  Recall from earlier that
=$HOST== is your hostname or IP address.

<example>
cd $REMOTELAB
bzr get sftp://$NAME@$HOST/$WORKLAB/lab1-src
</example>

You should see the message "Branched 1 revision(s).", which indicates
that bzr was able to successfully retrieve your Lab 1 work directory
and store it in lab1-src on mentor.

* Storing and syncing changes

When you make some changes to Lab 1 on your work machine, they may be
saved by changing to your work directory and typing the following,
replacing =$MESSAGE= with a comment that describes the changes you've
made.

<example>
bzr commit -m "$MESSAGE"
</example>

To make this change appear in your copy on mentor, log into mentor,
change to your work directory and run the following.

<example>
bzr pull
</example>

If you decide to make a change to your lab while on mentor, run =bzr
commit= as normal, and then run the =pwd= command -- the path it returns
will be used as =$DIR= later on.  To copy the change to your work
machine, do the following while logged into the work machine, in your
work directory.

<example>
bzr merge sftp://$NAME@mentor.ics.purdue.edu$DIR
bzr commit -m "Merge from mentor"
</example>

If you commit a second change to your lab while on mentor, run =bzr
commit= as normal.  Then on your work machine, do the following.

<example>
bzr pull
</example>

Note that you can omit the argument this time, because bzr remembers
it for you.

* Miscellanea

If you want to see what changes have not yet been recorded, run the
=bzr diff= command.

To discard changes that have been made since the last recorded change,
run =bzr revert=.

If you want to see which changes have been recorded, run =bzr log=.

To make a zip file of your project, run =bzr export ../lab1.zip=.
Likewise, running =bzr export ../lab1.tar.gz= will do what you
expect.