Using Subversion to Submit Work
This tutorial assumes you are using the command line. Whether you are using a Mac, Linux, or Windows,
I 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
In this class, you will use Subversion (abbreviated SVN) to submit all of your work. We will be using
PhoenixForge to manage the SVN
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 SVN itself, as well as instructions about how you will be using it to submit homework.
The easiest way to set this up is to have the initial subversion "checkout"
command create a new directory containing your entire, personal repository (or "repo").
Let's create such a directory and let's call it "mpcs51050-work", and make sure to replace the CNET ID in the url below:
cd ~
svn co https://phoenixforge.cs.uchicago.edu/svn/YourCNetIDHere-mpcs51050-spr-15 mpcs51050-work
Notice the URL above won't work as is, and also notice there is a deliberate space before "mpcs51050-work" above! The "co" is an abbreviation for "checkout."
When the above command succeeds, you now have your local copy of your
entire subversion repo for this class and it has been placed into a new
directory, named "mpcs51050-work." You can now do very simple
commands inside this directory to submit your homework. You can
also use this as your own version control system while tuning and improving your
homework.
Next let's switch into the repo directory.
cd mpcs51050-work
You are now in the directory that locally represents your svn repo.
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 checkout
command above, or within subdirectories like "hw1" and "hw2" (or further subdirectories
you create yourself).
Directory Structure
If you view the repo you pulled down above, you should see folders named "grades", "hw1", "hw2", etc.
The "grades" folder will contain your grades, while the other folders are where you will put your
homework, hw1 will be the first week's homework, hw2 the second week's, etc.
Commands
svn add
Use
svn add X
for each file X that you want place under SVN's control. Say you want to write some
code for homework 1 (or "hw1") and you want to put it into a file named hw1.c:
cd ~
cd mpcs51050-work
cd hw1
vim hw1.c
(...do some editing and save your changes...)
svn add hw1.c
svn ci -m "This is a first cut"
In the above sequence you created a file, added it to svn's "staging" area (svn
add), and you then checked-in your changes, committing them to the repo.
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. 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 up
Use
svn up
to update all files controlled by SVN to their newest versions.
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. (SVN will notify
you if there are conflicts that it can't resolve, but most of the time this
will just work.)
You can also use,
svn up someDirectory
to only perform the update on a single directory.
svn mkdir
Use
svn mkdir myNewDirectory
to create a directory in the repo.
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.
Note that if you use svn add *
that will also add existing directories and files to a repo.
svn stat
To see if you have local uncommitted changes, use
svn stat
or for more information,
svn stat -uv
These commands list files that have uncommitted changes (marked "M" for modified files, "A" for files to be added, and "D" for files to be deleted), and
files that have not been added or committed (marked with a "?"), called
"untracked" files in SVN.
Same git note as above, but it bears repeating:
be aware 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 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 is no longer part of your check-in.
This is a very important command to fix things when you
can see your check-in has some garbage in it, which frequently happens when you use recursive svn add commands.
svn del
Use
svn del myFile
if it's a similar scenario where you accidentally put something in the
repo, but in this case you unfortunately checked it in already.
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:
- Place work for a certain homework into folders named hw1, hw2, 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 Homework or Lab Deliverable (or the project if applicable) should be completely encapsulated
in its folder (again, hw1, hw2, etc). Within each homework folder, you can
structure your file storage however you want (create subfolders, organize
things to your pleasure et cetera).
You are required to include a README text file within this folder.
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 homework.
- 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 repository, and the URL looks like this, though it needs your CNET ID:
https://phoenixforge.cs.uchicago.edu/projects/YourCNETIDHere-mpcs51050-spr-15/repository .
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.
- Avoid accidentally changing files and running svn ci again, after the deadline.
An automated script is run to find activity in the homework directory after the time due, so if you touch your homework directory after
that, you can expect later in the quarter that your homework will be docked because of this.
The time that matters for determining the lateness penalty is
the time (on the SVN 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 to commit.
- "What time is it on the SVN 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:
date
svn ci -m "time testing" X
svn log X
The top entry in the "svn log" output contains the SVN 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.
- 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 SVN repo histories are forever.
Once you've committed/checked-in, the repo on the server will always require that added space
even if you delete 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.
Installing SVN
- Linux
If you are using Linux, you can install SVN from the command line:
sudo apt-get install svn
- Mac
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.
- Windows
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.
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
Slik Subversion,
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
Eclipse has a plug-in that integrates SVN called Subclipse: http://subclipse.tigris.org/. The installation guide can be found here: http://subclipse.tigris.org/install.html.
Further Reading
Here are some links to other (more detailed) SVN informationals:
This tutorial was adapted from Gordon Kindlmann's, which can be found here: http://people.cs.uchicago.edu/~glk/class/scivis/svn.html.