Using Subversion in Software Design
Spring 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 ssl.untyped.com, which Matt Jadud has been kind enough
to make available for us.

You each have an account on the server, and we have created a
repository for each of you and put Swampy into it.

Here are the operations you will want to perform:

1) First, you will copy your repository 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; your 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 all of your repositories.
   When you finish a homework and copy it to your repository, I will
   "update" my local copy of your repository, which will cause your
   changes to be reflected in my local copy.  Then I can read and
   execute your programs.

5) If I make any changes to Swampy, I will distribute them by copying
   them into my local copy of your repository and then checking them
   in.  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 will 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.  We will send your password to you by email.

   You also 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 https://ssl.untyped.com/svn/repos/olin/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 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 2."  

  
2) If you type "ls" you should see a new directory with a name like
   "first.last".  This is your local copy of the repository.

   Navigate into this directory and type "ls".  You should see
   the Swampy files.  Run TurtleWorld.py just to make sure.

   If you have already done Homework 1, you should have a file called
   hello.py in another directory.  Copy it into this directory and
   run it, just to make sure. 

   To notify svn that this file should be considered part of the
   repository, run

svn add hello.py

   You should get a message like "A  hello.py".


3) To check in your changes (in this case the added file), type

svn ci -m "Adding homework 1"

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

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

   https://ssl.untyped.com/svn/repos/olin/first.last

   You should see the new file there.


4) You don't do step 4.  I do step 4.


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

svn update

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


How to turn in Homework 1
-------------------------

1) Navigate into the local copy of your repository.

2) Make a directory for homework 1:

svn mkdir hw01

By using svn to make the directory, you get two operations for
the price of one: svn makes the new directory and "adds" it to
the repository.

3) Copy file(s) into the new directory.

svn cp hello.py hw01

Again, using svn to make the copy performs two operations: it
makes a new file called hw01/hello.py and "adds" it to the
repository.

4) Check in the changes.

svn ci -m "Adding hw01"


Note: please use exactly these names, 'hw01' for the directory
and 'hello.py' for the file.  That way I can automate the process
of running your code. 


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