A Subversion tutorial https://www.clear.rice.edu/comp314/svn.

htm
www.clear.rice.edu/comp314/svn.htm

Source control in ten minutes: a Subversion

tutorial
Comp314: Applied Algorithms and Data Structures (Rice University)

First version: 24-Jan-2006 by Dan Sandler

Introduction Table of Contents

An important element of the modern software development Introduction

Basics and command-line usage
process is source control (or version control). Cooperating The Subversion lifecycle
developers commit their changes incrementally to a common Checking out the repository
source repository, which allows them to collaborate on code Editing files
without resorting to crude file-sharing techniques (shared Updating local sources
drives, email). Source control tools track all prior versions of Committing changes
all files, allowing developers to "time travel" backward and Adding files
Looking around
forward in their software to determine when and where bugs Bonus feature: Web access
are introduced. These tools also identify conflicting Time travel
simultaneous modfications made by two (poorly- Resolving conflicts
communicating) team members, forcing them to work out the Using Subversion in this course
correct solution (rather than blindly overwriting one or the Getting Subversion for your computer
other original submission). Links

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
A Subversion tutorial https://www.clear.rice.edu/comp314/svn.htm
www.clear.rice.edu/comp314/svn.htm

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 or emacs, 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:

A Subversion tutorial https://www.clear.rice.edu/comp314/svn.htm
www.clear.rice.edu/comp314/svn.htm

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
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 Subversion tutorial https://www.clear.rice.edu/comp314/svn.htm
www.clear.rice.edu/comp314/svn.htm

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.
A Subversion tutorial https://www.clear.rice.edu/comp314/svn.htm
www.clear.rice.edu/comp314/svn.htm

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 trunk directory 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
A Subversion tutorial https://www.clear.rice.edu/comp314/svn.htm
www.clear.rice.edu/comp314/svn.htm

Last modified: 26-Jan-2006 by dsandler