SVN BASIC TUTORIAL

Introduction

An important element of the modern software development process is source control (or version control). Cooperating developers commit their changes incrementally to a common source repository, which allows them to collaborate on code without resorting to crude file-sharing techniques (shared drives, email). Source control tools track all prior versions of all files, allowing developers to "time travel" backward and forward in their software to determine when and where bugs are introduced. These tools also identify conflicting simultaneous modfications made by two (poorly-communicating) team members, forcing them to work out the correct solution (rather than blindly overwriting one or the other original submission).
In this course we will make available a Subversion repository for your use. Subversion is a modern replacement for the venerable (but fragile and aging) CVS system, which you may be familiar with. Subversion's command-line tools (for Unix, Mac, and Windows) operate quite similarly to their CVS counterparts, and excellent graphical tools exist (e.g. the Subclipse plugin for the cross-platform Eclipse IDE; the TortoiseSVN extension for the Windows graphical shell).
This document will get you started with the command-line tools and will point you in the right direction for some of these graphical tools. If you have problems or questions, please direct them to the rice.owlnews.comp314 newsgroup and the teaching staff will help you out.

Basics and command-line usage

In Subversion (often abbreviated SVN), code is stored in a repository, which is located somewhere on the network. (For COMP 314 we will provide the repository, but if you choose to use Subversion for your personal projects you can create your own repository as well.)
The essential Subversion lifecycle is the following:

1. Check out a project (a directory path) from a repository.
2. In that project directory, create or edit files and subdirectories.
3. Update your local copy from the repository, picking up changes your team members may have made since your last update.
4. Go to step 2. If you're ready to commit your changes, go to step 5.
5. Commit your changes to the repository. Go to step 2.

Let's get started with a simple example. Log into an Owlnet UNIX system and add the comp314 Subversion tools directory to your command path: (If you're using a shell other than csh, the necessary command might be different; see here for more about the available shells on Owlnet.)

% set path = ( $path /home/comp314/subversion )

Checking out the repository for the first time. Each repository has a URL from which it can be initially checked out; once that's done, the URL is remembered for future operations. Here's how to check out the comp314-students repository: ("co" is short for "checkout")

% svn co http://sys.cs.rice.edu/repos/comp314-students

The directory comp314-students will be created in your current directory. You can rename or move comp314-students anywhere you like; Subversion will remember the repository it refers to.
Go ahead and look around in comp314-students. There will already be a few directories there, including one called test. All students in the course have write access in this directory, so it's a good place to experiment with Subversion.
Editing a file. You don't need to do anything special to tell Subversion you'd like to change an existing file; it can figure it out from the fact that the file's contents will change when you edit it. Go ahead and edit the guestbook.txt file inside the test directory. Add a line for yourself and save your changes.
Updating your sources. Usually, before you make a checkin, it's a good idea to check to make sure nobody else committed changes while you weren't looking.

% svn update

Committing your changes. Now you're ready to commit your changes the the repository so your teammate(s) can see and build on them.

Unfortunate detour: Editors
When you invoke svn commit, Subversion will launch your "default editor" so it can ask you to add some comments to a text file. Unfortunately, the default editor on Owlnet is vi, a largely-inscrutable text editor preferred by bearded Unix nerds. Chances are you're more familiar with pico oremacs, so you'll want Subversion to launch that instead.
Run the command echo $EDITOR at your prompt. If nothing appears, you'll need to set a default editor to escape from vi. To do this, run the following command (substituting emacs for pico if you wish):
% setenv EDITOR pico
(This syntax is for csh, the Owlnet default shell.)
You'll probably want to add a line like that to your .login file so that your default editor is properly configured every time you start working. Now would be a good time to add that line, and the set path = … line mentioned above.

All right, back to the tutorial. When you're ready to check in your changes, run svn commit on the files or directories you've changed:

% svn commit guestbook.txt

Your default editor (see above) will be invoked on a temporary file; into this file you should type a short message explaining the purpose of your change. (For our guest book example this isn't particularly useful, but it becomes essential when you're looking back over your checkins and trying to figure out where you fixed—or created—a bug.)
You'll note that Subversion responds to your checkin with a message:

Sending guestbook.txt
Transmitting file data ...
Committed revision 3.

Each committed change is assigned a monotonically-increasing revision number. (In this example, that number was 3.) You can go back and examine any past checkin with svn log: (the -r flag lets you pick the revision to look at; the -v flag tells you what files were touched)

% svn log -v -r3
------------------------------------------------------------------------
r3 | dsandler | 2006-01-12 14:16:11 -0600 (Thu, 12 Jan 2006) | 1 line
Changed paths:
   A /test/guestbook.txt

Something for everyone to edit.

When should you commit? A good time to check things in is when you've made a substantial change that stands on its own. If implementing a new feature requires three files to be changed, change all three and commit them all together. (You can specify multiple files after svn commit to do this.) This way, each file's individual change (which may not stand on its own) is associated with the entire checkin.
If you happen to invoke svn commit but realize that you didn't really mean to commit all that stuff (or all those files), exit your editor without adding a commit message. You will be given a chance to back out. (Once you write and save a commit message, you've lost that opportunity.)
Adding a new file. Subversion can tell automatically when you change an existing file from the repository, but it doesn't know when you want to add a new file or directory to source control. For this you need to use svn add:

% echo "My new file." > (some new file).txt
% svn add (some new file).txt

At this point, you can commit this change like any other.
Taking a look around. You'll frequently want to check to see what you've edited and what you haven't, often before a svn commit command.

% svn status

You'll get a list of the files in the current directory, with flags (such as M for modified) next to each file describing its status in your local copy.
Remember the lifecycle. svn co, svn update, (edit or add), svn status, svn commit.
Finally, if you forget how to use a Subversion subcommand, or want to find out about the other features of the svn tool, use svn help.

Bonus feature: Web access

Because our comp314 repository uses the http:// access method, you might wonder if you can actually treat the repository like a web page and view it in your browser. The answer is, "yes!" Access through a browser is read-only, but it lets you poke around the repository and see what you can see (with your own credentials). Try it: http://sys.cs.rice.edu/repos/comp314-students.

Time travel

One of the most powerful features of version control systems is history. The repository records all changes made, and the "clock" can be wound backward and forward to show you any past or present version of any file.
A simple thing to try is to inspect the log to see what's been done in a given directory (and its children):

% cd mycode/comp314-students
% ls
projects/        test/
% svn log -v test
------------------------------------------------------------------------
r3 | dsandler | 2006-01-12 14:16:11 -0600 (Thu, 12 Jan 2006) | 1 line
Changed paths:
   A /test/guestbook.txt

Something for everyone to edit.
------------------------------------------------------------------------
r2 | dsandler | 2006-01-12 14:12:43 -0600 (Thu, 12 Jan 2006) | 1 line
Changed paths:
   A /test
   A /test/README

Add test directory.
------------------------------------------------------------------------

You can use the -r flag to get the svn log for a particular revision number or range of revisions. -r can also be used with svn up (update) or svn co(checkout); in this way you can get a snapshot of your code at any point in the past (for example, before you introduced that nasty Heisenbug).

Resolving conflicts

(incomplete, but you can read the Subversion book's section on conflicts)

Using Subversion in this course

You will be assigned to a numbered project group for each project; we will create a directory for you to use (with your teammate) for that project. You won't be able to see other groups' directories (and if you do, please obey the Honor Code and let us know so we can fix it). So if you happened to be in Group 4 for Project 0, you might see the following when you check out the 314 repository:

% svn co http://sys.cs.rice.edu/repos/comp314-students my314
Username: (your-username-here)
Password for '(your-username-here)': XXXX
A  my314/test
A  my314/test/guestbook.txt
A  my314/test/README
A  my314/projects
A  my314/projects/project0
A  my314/projects/project0/group4
A  my314/projects/project0/group4/trunk
A  my314/projects/project0/group4/branches
A  my314/projects/project0/group4/tags
Checked out revision 7.

You'll notice that for each group, for each project, we create three directories for you: trunk, branches, and tags. This is the recommended directory layout for individual projects in Subversion, and we follow that convention in the comp314 repository.
The trunk directory is where you typically do your work. Create files here, edit them, check them in, compile them. Think of the trunk as your home directory for the purposes of any given project. In fact, for beginners this is probably the only directory you'll use.
The branches and tags directories exist when you want to move on to more sophisticated parallel development. For example, branches are copies of the code that evolve independently. On large projects this can be important when multiple parties are making substantially different changes to the code; you probably won't need to use them in this course.
Tags, on the other hand, are more likely to be of use to you. A tag represents a snapshot of your code at a single point in time. You might, for example, set a tag on your code at the prototype stage, so you can always conveniently refer back to this version of things.
Tag Example

% cd projects/project0/group18/trunk
% emacs MyCode.java
% svn add MyCode.java
A MyCode.java
% svn commit
[enter a message in your editor, save and close]
Sending MyCode.java
Transmitting file data ...
Committed revision 38.
[Maybe this is your finished prototype, so let's take a snapshot.]
% cd ..
% ls
branches/ tags/   trunk/
[Now we'll use "svn cp" to copy the trunk, as it exists right now,
 to a new spot underneath tags.]
% svn cp trunk tags/prototype
A tags/prototype
% svn commit trunk/prototype
[enter a message along the lines of "Taking a snapshot of the prototype
 we're turning in."]
Sending tags/prototype...
Committed revision 39.
% ls trunk/
MyCode.java     # <-- your working code; continue to develop here
% ls tags/
prototype/
% ls tags/prototype/
MyCode.java     # <-- this version is frozen in time

You can read a lot more about tags and branches in Chapter 4 of the Subversion book; if this all seems really esoteric, just do all your work in the trunkdirectory and you'll be all set.

Getting Subversion for your computer

• Windows users: Perhaps the best SVN interface is TortoiseSVN, a Windows shell extension which augments the file explorer to show SVN status badges on any files that are under version control. You can also install the command-line tools, available from this directory (look for svn-win32-VERSION-setup.exe).
• Mac users: You can download the command-line tools (packaged, mercifully, as standalone executables) here. There is a graphical client, SvnX, if you want to play with it.
• Linux users: Your distribution probably has "subversion" or "svn" packages you can install; ask your system's package tool (apt-get or yum or what have you). Alternatively, you can install monolithic binary versions of the command-line tools from here.
• Eclipse users: There's an excellent Eclipse plug-in for called Subclipse that adds Subversion support to Eclipse's source control features (alongside the built-in CVS support). The installation guide is well worth reading.

Links

• Subversion source control system (home page)
• Version Control with Subversion: the official manual
• Subclipse: SVN integration for the Eclipse Java IDE