Using Subversion to Submit Work

This tutorial assumes you are using the command line. Whether you are using a Mac, Linux, or Windows, we highly recommend using the command line. If you need extra help figuring this out or have never used the command line, e-mail the TAs for help; don't be shy!

Introduction

First a note in particular for those on Windows or similar systems that never have the svn command pre-supplied. This document is structured with installation instructions at the bottom because many systems, like Macs and most Linux machines already have the svn command installed. If you are not on such a system and you really need to get Subversion installed first, please switch to the installation section of this document and continue on at this point in the document only when you have everything working nicely at your system's command line. Even on a Mac or similar system that you believe has Subversion ready to go, you may want to look at the installation section now to ensure everything is in order.

In this class, you will use Subversion (abbreviated SVN) to submit all of your work. We will be using PhoenixForge to manage the Subversion repositories associated with the class. Your authentication on PhoenixForge, and the svn commands that connect to PhoenixForge, will be via your University CNetID and its password. Read this entire document; it contains information about Subversion itself, as well as instructions about how you will be using it to submit work. The easiest way to set this up is to have the initial Subversion "check out" command create a new directory containing your entire personal repository (or "repo"). Let's create such a directory and let's call it "mpcs56600-work", and make sure to replace the CNET ID in the url below: 
cd ~
svn co https://phoenixforge.cs.uchicago.edu/svn/YourCNetIDHere-mpcs51205-aut-19 mpcs51205-work
Notice the URL in the svn command shown here won't work as is, and also notice there is a deliberate space before "mpcs51205-work." The "co" is an abbreviation for "check out" and svn checkout is equivalent to svn co.

When the above command succeeds, you now have a local copy of your entire Subversion repo for this class and it has been placed into a new directory, which we named "mpcs51205-work." You can now do very simple commands inside this directory to submit your work.

You can also use this as your own version control system while tuning and improving your work. You can view project and file histories, diffs, etc (similar to let's say github) using the PhoenixForge website. Log in using your CNet ID.

Next let's switch into the repo directory. 

cd mpcs51205-work

You are now inside the directory that locally represents your svn repo.

Notice that you can do the above commands anywhere, so you can have your repo wherever you are: on your Mac, Windows, or Linux laptop, on your desktop, or on a University compute cluster machine.

From this point on you really only need to know three or four svn commands. You execute these commands from within the directory created by the svn co (aka svn checkout) command above or within subdirectories of it.

Directory Structure

If you view the repo you pulled down above, you should see folders named "grades", "lab_1", "lab_2", etc. The "grades" folder will be filled in by the graders, while the other folders are where you will put your work.

Commands

svn add

Use 

svn add X
for each file X that you want to place under SVN's control.

Say you want to work on Lab 1 and you create two files named first.cpp and second.cpp. 

cd ~
cd mpcs51205-work
cd lab_1
vim first.cpp
(...do some editing and save your changes...)
vim second.cpp
(...do some editing and save your changes...)
svn add *.cpp
svn ci -m "This is where you say what these files mean"
In the above sequence you created files, added them to svn's "staging" area (via svn add), and you then checked-in your set of changes (via svn ci), committing all the changes to the repo and including a descriptive note.
Note that Subversion will force you to add this descriptive note by popping up an editor if you do not enter your commit message directly on the command line. Students usually find these editors annoying, and on some platforms they fail to even work and cause the whole command to fail. As a result, it's usually easiest to enter it on the command line as shown in this tutorial.
A Git note: be aware that there is no need to "stage" modified files in subversion as there is in Git. When you do an svn ci command in a directory, it will automatically check in modified files (in that directory). So svn add is only needed for new files and new directories.
The ci command means "check-in." You can also use svn commit instead of svn ci if you prefer that nomenclature. The -m argument means "message" and allows you to skip a prompt for a commit message which svn will otherwise force you to deal with. (Note that on Windows, this prompt can be a problem, which is another reason why it's better to put the message right into the -m argument as shown. See the install section below for more on that problem.)

You can also use 

svn add *
to add everything in a directory, including all directories.

svn revert

Use 

svn revert myFile
if you have a problem because you just used svn add and you see (via svn stat) that it added some junk or temporary files that you did not mean to add and you are catching this before doing your check-in. After running svn revert the file is removed from the "staging" area and will no longer be part of your next check-in. This is a very important command to fix things when you can see your check-in has some garbage in it, which can happen when you use recursive svn add commands.

svn ci (or svn commit)

Use 

svn ci -m "Put a descriptive message here"
to send all your current changes (including additions or even deletions) to the server. This is the most important command for you to know to actually submit your work, and the time when this command succeeds is the time that counts for when your work is considered officially received.

The command svn commit is exactly the same thing as svn ci.

svn up

Use 

svn up
to update all files on your machine with the latest changes from the server. This is particularly useful for you to do from the top level repo directory to see the latest grades you have in your "grades" directory. Also, if you checkout a copy of a repository on two separate machines, then add, modify, and commit files on one of the machines, you can use this command on the other machine to update the files with the new changes - even if you've also made changes on that same machine being updated.
Regarding such multi-machine merges, Subversion will notify you if there are conflicts that it can't resolve, but most of the time this will "just work." Subversion is quite good at this. In most cases the two sets of changes do not affect identical lines and when that's true Subversion can usually figure things out by itself. Of course if the same line has changes on the server and changes made by you, then there is no way around a manual merge, and Subversion will put up an alert telling you that it cannot resolve the changes and needs your help.

You can also use, 

svn up someDirectoryOrFile
to only perform the update on a single item.

svn mkdir

Use 

svn mkdir myNewDirectory
when you want the repo to have a new directory. The directory is created for you on your local filesystem.

You can also use 

svn add myExistingDirectory
to add a directory that already exists. This command is recursive and will add everything inside the directory. Be careful with this as you will be penalized if your directory contains large temporary or intermediate files that really should not be in your check-in. Note that if you use svn add * that will also add existing directories as well as files to a repo.

Just like with other commands that change things, the changes are only reflected on the server at your next check-in.

svn stat

To see if you have changes that have not been checked-in, use 

svn stat
or for more information, 
svn stat -uv
These commands ignore files that are identical on both your machine and the server. They only list files that have changes and files that have never been added or committed. Files with changes could be marked "M" for modified, "A" for newly added, "D" for deleted as well as a couple other less frequently seen types. Files that are not in the repo are marked with a question mark character ("?").
Another Git note: It bears repeating that there is no need to "stage" modified files in subversion as there is in Git. So files marked "M" in svn stat will automatically be updated on the server at the next check-in.

svn del

Use 

svn del myFile
to remove a file when the file has already been checked-in to the repository. For example, it could be a similar scenario to the "svn revert" described above, but where you accidentally checked the item in. You can use svn del to remove it, but note that Subversion never gets rid of history, so this is not a good way to fix a problem with accidentally checking-in an inappropriately large file. Such problems should be prevented before check-in, not after.

svn log

Use 

svn log
to see a history of the commits (aka. check-ins) in the current directory.

Submitting Work

Because svn ci is how you are handing in your work, be careful with it. Its proper use is your responsibility. In particular:

Installing Subversion

Further Reading

Here are some links to other (more detailed) Subversion informationals:

This tutorial was adapted from Gordon Kindlmann's, which can be found here: http://people.cs.uchicago.edu/~glk/class/scivis/svn.html.