Using Subversion in Computational Modeling
Fall 2008

Subversion, abbreviated svn, is a suite of programs for managing
repositories.  A repository is an archive that keeps track of
successive versions of electronic documents.  A repository is often
(but not necessarily) on a remote server; for this class we will use a
server called svn.allendowney.com, which is maintained by an
off-campus hosting service.

For this class, there is only one repository---it contains a directory
for each of you.  You all have read/write access to all directories,
so you should not put anything in your directory that you don't want
to share.  I have put some files in each of your directories to help
get you started.

Here are the operations you will want to perform:

1) First, you will copy your directory from the server to your
   laptop.  This is called "checking out" (by analogy with checking a
   book out of a library).  The copy of the repository on your laptop
   is called a "local copy" or "working copy."

2) Next you will navigate into the newly-created directory and either
   modify existing files or add new files and directories.  If you add
   a new file or directory, you have to tell svn about it.  This
   operation is called an "add", but that name is a little misleading;
   it would be more precise to say, "notify svn about a new addition."

3) When you are ready to copy your changes and additions back to the
   repository, you "check in" (again, by analogy with a library).
   This operation is also called "commit", because by copying your
   changes back to the repository, you are making the changes
   permanent.  But don't be afraid of committment; the repository
   keeps track of all prior versions, so if you commit a change and
   then regret it, you can always "revert" to a prior version.

4) On my hard drive, I keep a local copy of the entire repository.
   Periodically I will "update" my local copy, which will cause your
   changes to be reflected in my local copy.  Then I can read your
   materials and execute your programs.

5) In some cases I will distribute materials by putting a copy in
   your directory.  Then I will notify you to update your local copy.

Now here are the details about how you perform each of those
operations:

0) In order to access your repository, you need a username and
   password.  Your username is the same as your Olin email address,
   without the @students.olin.edu part.  So, for example, my username
   is allen.downey.  I will tell you your password in class.

   You may need to install the subversion client (you don't need the
   server).

   On Ubuntu, run "sudo apt-get install subversion"

   On Fedora, I believe you can "yum install subversion",
   but I haven't confirmed that that's the right package name.

   On Windows, you can install TortoiseSVN.


1) To check out your repository, create a terminal and navigate
   to your home directory.  Then type

svn --username first.last co http://svn.allendowney.com/cm08/first.last

   All svn commands begin with "svn" followed by an operation
   and other arguments.  In this case the operation is "co",
   which stands for "check out" and the argument is the URL
   of your directory in the repository.

   Of course, you should replace "first.last" with your name.

   You will be prompted for your password.  Type your password and
   hit return.  You should get a message like "Checked out revision XX,"
   where XX is the number of the current revision.  Every time someone
   checks a revision into the repository, this number gets incremented.

  
2) If you type "ls" you should see a new directory named cm08 with
   a subdirectory named "first.last".  This is your local copy of 
   your directory.

   Navigate into this directory and type "ls".  You should see
   a Makefile, a couple of latex files and a subdirectory named figs.
   
   Edit book.tex and put your name where it says, "Your name here."
   Subversion will see that this file has changed and upload it to
   the repository the next time you check in.

   Create a new file named junk.tex and put a few characters in it.
   To notify svn that this file should be considered part of the
   repository, run

svn add junk.tex

   You should get a message like "A  junk.tex".


3) To check in your changes, type

svn ci -m "Adding junk.tex"

   You should get a series of messages telling you what svn is
   doing, ending with something like, "Committed revision XX."

   To confirm that the server has the new file, you can use
   a browser to view

   http://svn.allendowney.com/cm08/first.last

   You should see the new file there.


5) If I notify you that I have committed a change to the
   repository, you should navigate into your local copy and run

svn update

   If you do that now, you should get a message like
   "At revision XX," which indicates that your local copy
   is the same as the repository copy.


How to make compmod.pdf
-----------------------

If you cd into your directory and type 'make', it should compile
book.tex and produce compmod.ps.  If you type 'make pdf', it makes
compmod.pdf.

These new files are called "derivative files" because they are derived
from source code.  In general, you don't want to check derivative
files into a repository because (1) they tend to be big, and (2) if
you have several people working on a project, derivative files create
unnecessary conflicts.


That's all for now.  If you want more information about
Subversion, there are several good guides online, including
am excellent, and free, book at

http://svnbook.red-bean.com/

And several tutorials at

http://polishlinux.org/apps/subversion-howto/
http://www.linux.com/articles/45381
http://www.onlamp.com/pub/a/onlamp/2002/10/31/subversion.html