Table of Contents
- Introduction
- 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
- Links
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:
- 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:
(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 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 fromvi
. To do this, run the following command (substitutingemacs
forpico
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 theset 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 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
oryum
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