Source control in ten minutes: a Subversion tutorial
First version: 24-Jan-2006 by Daniel Sandler
Updated: 12-Jan-2010 by Michael Dietz
- Basics and command-line usage
- The Subversion lifecycle
- Checking out the repository
- Editing files
- Updating local sources
- Committing changes
- Adding files
- Looking around
- Bonus feature: Web access
- Time travel
- Resolving conflicts
- Using Subversion in this course
- Getting Subversion for your computer
- Eclipse support
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 or Subversive plugins 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 visit or email the course staff.
In Subversion (often abbreviated SVN), code is stored in a repository, which is located somewhere on the network. (For comp314 we will provide the repository, but if you choose to use Subversion for your personal projects you can create your own repository as well.)
- Check out a project (a directory path) from a repository.
- In that project directory, create or edit files and subdirectories.
- Update your local copy from the repository, picking up changes your team members may have made since your last update.
- Go to step 2. If you're ready to commit your changes, go to step 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:
% set path = ( $path /home/comp314/subversion )
bash users will instead type:
$ export PATH=$PATH:/home/comp314/subversion
(If you're using a shell other than
the necessary command might be different; see here for more about the available shells on Owlnet.)
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-10 repository: ("co" is short for "checkout")
% svn co https://svn.rice.edu/r/comp314-10
comp314-10 will be created in your
current directory. You can rename or move
anywhere you like; Subversion will remember the repository it refers
Go ahead and look around in
comp314-10. 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
% svn update
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 $EDITORat your prompt. If nothing appears, you'll need to set a default editor to avoid invoking
vi. To do this, run the following command (substituting
picoif you wish):
% setenv EDITOR pico
This syntax is for csh, the Owlnet default shell; if instead you are using bash, you'll want to type:
$ export EDITOR=pico
You'll probably want to add a line like that to your
.loginfile (bash users:
.profile) 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
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
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
% echo "My new file." > (some new file).txt % svn add (some new file).txt
At this point, you can
commit this change like any
% svn status
You'll get a list of the files in the current directory, with flags
M for modified) next to each file
describing its status in your local copy.
Remember the lifecycle.
svn update, (edit or add),
Finally, if you forget how to use a Subversion subcommand, or want to find out about the other features of the
svn tool, use
Because our comp314 repository uses the
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: https://svn.rice.edu/r/comp314-10.
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-10 % 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).
(incomplete, but you can read the Subversion book's section on conflicts)
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 1, you might see the following when you check out the 314 repository:
% svn co https://svn.rice.edu/r/comp314-10 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/p1 A my314/projects/p1/g4 A my314/projects/p1/g4/trunk A my314/projects/p1/g4/branches A my314/projects/p1/g4/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 beta stage, so you can always conveniently refer back to this version of things.
% cd projects/p0/g18/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 beta, 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/beta A tags/beta % svn commit trunk/beta [enter a message along the lines of "Taking a snapshot of the beta we're turning in."] Sending tags/beta... Committed revision 39. % ls trunk/ MyCode.java # <-- your working code; continue to develop here % ls tags/ beta/ % ls tags/beta/ 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.
- 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
- Mac users: You can download the command-line tools (packaged, mercifully, as standalone executables) here. There are a few graphical clients, including scplugin that integrates with the Finder (à la Tortoise).
- Linux users: Your distribution probably has "subversion" or "svn" packages you can install; ask your system's package tool (
yumor what have you). Alternatively, you can install monolithic binary versions of the command-line tools from here.
The original Eclipse plug-in for Subversion was Subclipse, giving you some nice integration with Eclipse's built-in source code control features. A newer plugin, which seems to be the preferable option now, is Subversive. Before you install either one, make sure you read the installation instructions carefully (subclipse instructions, subversive instructions).
If you install subversion support into Eclipse, you may still find it to be helpful to have the other tools listed above.