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!
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
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
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:
svn co https://phoenixforge.cs.uchicago.edu/svn/YourCNetIDHere-mpcs56600-spr-19 mpcs56600-work
Notice the URL in the svn command shown here won't work as is, and also notice there is a deliberate space before "mpcs56600-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 "mpcs56600-work." You can now do very simple
commands inside this directory to submit your work.
also use this as your own version control system while tuning and improving your
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.
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.
If you view the repo you pulled down above, you should see folders named "grades", "lab1", "lab2", etc.
The "grades" folder will be filled in by the graders, while the other folders are where you will put your
for each file X that you want to place under SVN's control.
svn add X
Say you want to work on Lab 1 and you create two files named first.cpp and second.cpp.
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.
(...do some editing and save your changes...)
(...do some editing and save your changes...)
svn add *.cpp
svn ci -m "This is where you say what these files mean"
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
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
to add everything in a directory, including all directories.
svn add *
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 revert myFile
svn ci (or svn commit)
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.
svn ci -m "Put a descriptive message here"
The command svn commit is exactly the same thing as svn ci.
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,
to only perform the update on a single item.
svn up someDirectoryOrFile
when you want the repo to have a new directory. The directory is
created for you on your local filesystem.
svn mkdir myNewDirectory
You can also use
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 add myExistingDirectory
To see if you have changes that have not been checked-in, use
or for more information,
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 ("?").
svn stat -uv
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.
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 del myFile
to see a history of the commits (aka. check-ins) in the current directory.
Because svn ci is how you are handing in your work, be
careful with it. Its proper use is your responsibility. In particular:
- Place work into folders named lab1, lab2, etc.
These folders have been pre-created for you, so you should not need to use svn mkdir or svn add to create them.
Each deliverable (or any term project) should be completely encapsulated
in its folder. Within each folder, you can
structure your files however you want, creating subfolders, organizing
things to your pleasure, etc.
You are expected to include a README text file.
You can use this file to explain how to run your code, especially if it's done in an esoteric or very particular way, but
in most cases it's better if you spend most of your time in the README explaining the workings of your code a bit,
because that is what is interesting about your work.
- If you haven't done an svn add and svn ci, it hasn't been handed in.
Use svn stat to see uncommitted changes and untracked files.
Make sure that you have done an svn add on all the files you want to hand in.
- You can double check that the files you think you have handed in, have really been handed in.
Associated with every per-student subproject is a web-based view of the SVN repo, and the URL looks like this, though it needs your CNET ID:
Use this URL with your CNET ID added to confirm what the graders will see when they use an svn update to collect your files, and to make sure that you have
not submitted an empty ("0 Bytes") file by accident.
You can also use this second URL to get a very simple view of the files in your repo (again, this URL needs have your CNET ID spliced in):
- Avoid accidentally changing files and running svn ci again, after the deadline.
An automated script is run to find activity in work directories after the time due, so if you touch these directories after
that, you can expect later in the quarter that your grades will be docked because of this.
The time that matters for determining the lateness penalty is
the time (on the Subversion server) of your last commit within a given assignment subdirectory.
You can prevent accidental late hand-ins by not making any changes after your final svn ci;
that way there are no changes that could get accidentally committed. Though modified files are automatically
included in commits to the server, this is only true for the directory you are in. So if you are in the lab2
directory and do an svn ci, that command will not automatically commit
changed files in the lab1 directory (and this is good).
- "What time is it on the Subversion server?" you might ask, if you suspect that the SVN server's
clock is running fast, thus putting you at a disadvantage. You can figure this out, well before
the deadline. After a local modification to file X, you can do something like:
The top entry in the svn log output contains the server's record of the commit time,
which you can compare to what your local computer reported via "date" just before the commit. This is just like the svn log commands above,
but brings up the logs for file X only.
svn ci -m "time testing" X
svn log X
- Very large submissions into subversion will be docked points. Project directories
for some programming language IDEs can be huge. Perhaps the worst offender is
Microsoft Visual Studio, with lots of enormous files that may total 50 MB even
for a "Hello, world" program.
As stated above, your submission is your responsibility and if you submit something that
is way over say 1 or 2 MB, unless the assignment specifically calls for it, you will be docked.
Be aware that Subversion repo histories are forever.
Once you've committed/checked-in, the repo on the server will always require that added space
even if you use svn delete to remove the improperly submitted material later.
On Mac or Linux, use the command `du -s -m *`
to view the disk space usage of your material from the command line.
Use the svn revert command described above
to fix problems when you catch these large submissions before you check them in.
If you are using Linux, or rather if you are using Debian or Ubuntu or any
other Debian-derived distro, you can install Subversion from the command line:
On Fedora and RedHat-derived distros, it's very similar:
sudo apt-get install svn
sudo yum install svn
Mac machines should already have svn installed on them. If you don't have it, you can find it here: http://subversion.apache.org/packages.html. I suggest the Wandisco download link.
If you are using Windows, the most popular SVN client is TortoiseSVN: http://tortoisesvn.tigris.org/,
but it does not by default install the svn command line described on this page! So we do not recommend it.
TortoiseSVN integrates into Windows Explorer (the file browser), which can be quite nice, and provides other nice UI features,
but as stated above, we recommend that you simply use the command line svn client described on this page,
and for that, the simplest option is
which is regularly updated and great when
you just want the same svn command you use on Mac or Linux.
Click below to get Slik SVN:
- Download Slik SVN Client - svn command line
Make sure to update your PATH environment variable after install.
Also make sure to use svn ci -m "my check in message" (or identically, svn commit -m ...)
when doing check-ins so that subversion doesn't try to find an editor on
your system to force you to enter a check-in message.
On Windows, there may be no suitable editor for it to find!
If you go the TortoiseSVN route, make sure you change the install options to include the command line tools as well.
For TortoiseSVN GUI equivalencies, the following pages almost completely correspond to the command-line information above:
The documentation for TortoiseSVN can be found here: http://tortoisesvn.net/docs/release/TortoiseSVN_en/index.html.
Eclipse has a plug-in that integrates Subversion called Subclipse: http://subclipse.tigris.org/. The installation guide can be found here: http://subclipse.tigris.org/install.html.
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.