Step-by-step instructions to using SVN

Motto: The palest of ink is better than the best memory.
Chinese proverb

Introduction

This page is set up to guide you through using SVN, a tool for file versioning. If you are moderately versed in SVN, you can safely skip this section.

For your project, you'll be starting from a codebase provided by us and you will modify it extensively. Oftentimes, you'll find yourself in the situation of having modified the code in ways that render it unusable (such as during that 3 am coding binge), and you'll want to return to a previous version of your code, which you know it is stable. So you want to "turn the clock back".

Also, when two students are working on the same project, you'll want to be able to make changes to files concurrently and be able to merge changes into a single codebase. Things can get rapidly out of control when using improvised tools (email, "Are you changing file X? Oops..." and so on).

On top of that, we (instructor and TA) might occasionally fix the elusive last bug in the codebase, and you'll need to merge those bug fixes with your own code that already contains your additions and changes. That might sound like magic, but it turns out there are simple line-oriented algorithms that can do a great job at merging similar text from various sources. A robust tool implementing such algorithms is SVN, the SubVersionN version control system.

Working with SVN for CSE401

Here are the steps you need to take.

1. Make sure you have access to a Unix command prompt. You can obtain a Unix-like environment on Windows machines by downloading and installing Cygwin.
2. Execute a remote shell into one of the instructional machines (e.g. attu, amlia, kiska, or umnak—see also more information on available resources) by typing:

   % ssh your_cse_username@instructional_server
   

3. Execute the following command to start a shell with proper credentials for your group:

   % chgrpsh +cse401x
   

   x is a placeholder for a letter that will be assigned to by your TA. Students doing joint work will share the same letter. It looks like nothing has happened, but in reality you are now a member of the group cse401x for the remainder of the session. You can check that by typing:

   % groups
   

   You should see cse401x among your groups.
4. Make sure you can run svn, for now just by typing:

   % svn
   

   at the command prompt (%). You ought to see a help message.
5. Next, you'll need to create your own repository so you can reap the benefits of SVN. The repository is a directory that you should see as private to SVN. Manipulate that directory through SVN only.

   You create a repository by executing the svnadmin create SVN command, like this:

   % svnadmin create /projects/instr/qtr/cse401/x
   

   (where qtr is the code for the current quarter, e.g. 07au)
6. Now, you'll need to get the fresh code into your repository for the first time. To do that, create a temporary directory (let's call it temp), change to that directory, copy there the zip file that we distribute, and issue the following svn import command.

   % cd temp
   % unzip MiniJavaSVN.zip ; rm MiniJavaSVN.zip
   % svn import . file:///projects/instr/qtr/cse401/x -m "Initial release"
   

   The first . specifies what directory to import (i.e. the current one); the second URL specifies the location of the repository. (SVN uses URLs for most of its commands, not regular file paths.) The -m "Initial release" is a checkin message; you'll see that a lot. After importing, remove the temp directory.
7. Now, you have everything up and you may want to start doing some actual work. You can checkout everything in SVN by incanting:

   % svn co file:///projects/instr/qtr/cse401/x/trunk <myproj>

   You should get pretty much the same files that were in the zip file, in the directory <myproj> of your choosing. Make sure you include the /trunk on the repository URL, or else your checkout will not reflect the directory layout you expect!
8. Whenever you are pleased with the quality of your code, you may want to check it in the repository:

   % cd myproj
   % svn ci -m "Added cool feature"
   

9. Whenever you are particularly pleased with the quality of your code, and want to tag that revision with a name (e.g. "ParsingWorking", or "ProjectMilestone1"), use the svn copy command:

   % svn copy file:///projects/instr/qtr/cse401/x/trunk \
                       file:///projects/instr/qtr/cse401/x/tags/tagname \ 
         -m "Tagging this fantastic release of my awesome project."
   

   This makes a clean backup copy of your code at the given tagname, and you can use these tags similarly to any other revision.
10. As said, on occasions we may distribute new, updated zip files, which you want to merge into your codebase. We will give you more specific instructions later, when this situation arises.
11. Whenever you want to refresh your local copy (directory myproj) with the contents of the SVN repository, e.g. after importing patches from us, you issue a cvs update command:

    % cd myproj
    % svn update
    

    Again, no need to specify the root directory because SVN looks it up in SVN/Root that the checkout command had created.
12. On occasion, you will need to add new files to your repository.

    If you're adding new files, say "coolfeature.java", then you need to issue:

    % svn add coolfeature.java
    

    The next time you do a svn ci, your new files will be added to the repository.