Skip to Content

Subversion Introduction

Posted on 13 mins read

Using Subversion in Class

Repositories (sometimes called source code repositories even though they are used to store much more than source code) are valuable software engineering tools in that they provide a central storage place for all team files, coordinate the sharing and update of team files, and remember the history of all changes to all files, which can be very valuable in understanding why a certain product is the way it is at a certain point in time.

In the repository model of working, the files that an individual works with on their own computer are simply temporary copies of the official copy in the repository. This temporary space is called the individual’s __working copy __or workspace. The way that an individual works on the project is as the following:

  • They check out the latest copies of the files from the repository;
  • They make local modifications to the files they need to work on in their workspace;
  • Then when they are satisfied with their changes, they check in their changes back into the repository.

In this class you are going to use Subversion to submit your assignments, and then ultimately use it for your teamwork as well.

There is an entire book describing how Subversion works, at http://svnbook.red-bean.com , but please do not print this book out! Most of it is not useful to you. I would, however, recommend reading chapters 1 and 2, which will give you a good idea of what repositories do and how to use them.

Using the Class Repository

The class repository is controlled by a server, and is at a URL equal or at least similar to:

svn://anonymous.cs.nmsu.edu/cs371faYYYY

where YYYY is the current year. This URL does not work in your web browser, but does work with a variety of Subversion clients. I will describe the basic command line client, which is the command “svn”. You can find graphical clients but I would recommend understanding how repositories work by using the command-line client before using one of the graphical clients.

I have already created a personal repository for each of you (which is just a directory within the class repository. The first thing you must do is to “check out” the initial copy of your repository. You can do this by doing:

svn checkout svn://anonymous.cs.nmsu.edu/cs371faYYYY/yourUsername --username yourUsername --password yourPassword

Your username should be the same as your CS username (not your NMSU username), and your password is your Banner/Aggie ID. This checkout command will create a directory in your current directory (so do this at a logical place in your homespace) that is named “yourUsername”. This is your working copy. If you “cd” into this directory, and then do the command “ls -a”, you will see a file named “Readme” and also a subdirectory named “.svn”. This hidden directory is how Subversion keeps track of your working copy.

Once you check out a working copy, you don’t really ever need to check it out again. Of course, you __can __check out another working copy somewhere else, or even delete this working copy (if it does not have any changes in it that have not yet been checked in to the repository), and then check it out again later, but the easiest thing to do is just to keep working in this working copy.

Checking In Changes

Now that you have a workspace (your checked-out working copy of the repository), you can start creating content and checking it into the repository.

Assuming you are in the root directory of your workspace (the directory named “yourUsername” that was created when you did “svn checkout”, now do:

mkdir lab1
cd lab1

Now create the required file in this directory using your favorite editor. For lab 1 you should create a Java or C/C++ program that prints “Hello World!”.

Now you must tell Subversion that this new directory and all its files should be placed in the repository (and thus controlled by the repository). We use the “add” command, as:

cd ..
svn add lab1

The first command goes back up to the root workspace directory, and then the final command tells Subversion to add lab1 and anything in it to the repository. You should have seen something like:

A lab1/
A lab1/Hello.java

which means that the files were successfully added.

The key here is that new files are not automatically added to the repository. You have to tell Subversion you want them in the repository. This is because you might create scratch files that you don’t ever want to be stored in the repository; your workspace can contain them, but you don’t want them saved. An example is “.class” files; these can always be recreated by running “javac”, and so you should not store them in the repository.

Another key issue is that your files ARE NOT yet saved in the repository! The “add” operation is entirely local in your workspace! To store all your updates back into the repository you must do a “commit” operation, like such:

svn commit -m 'Initial copy of lab 1'

It is the commit operation that finally takes the local modifications in your workspace and sends them to the repository. It is only when a commit operation succeeds that you know for sure that your changes are safely on the repository. The commit operation needs to have an information message that describes the changes being committed, which is the purpose of the “-m” option along with the single-quoted string (the message). You must always provide a message, and if you do not have one on the command line, subversion will pop up an editor for you to enter one in, and the editor just might be something ugly like “vi”!

Other General Operations

The most useful Subversion operations are:

  • svn status: this operation shows you the current status of your workspace. For files that are up to date and not locally modified, it prints nothing. For files that you have locally modified and not committed yet, it prints their name with an ‘M’. For files you have added but not yet committed it prints an ‘A’. For files that are not under control of the repository it prints a ‘?’ (if you want them in the repository you would need to “svn add” them). There are other notations used as well, but these are the most common.
  • svn update: this operation grabs changes that are in the repository and merges them into your workspace. For individual assignment files, since you are the only one working on them you probably won’t need to get updates, but for team work this is a very important operation.
  • svn cleanup: some times things go wrong and this will often straighten out your workspace and allow you to do a successful “svn commit”.
  • svn help: this gives you online help, and you can follow the word “help” with a particular command name and get help for that particular command.

Note that all of these commands work in any directory in your workspace, from the root on down in any subdirectory. They will only apply to the directory you do them in, and any subdirectories. Some of the commands can even be applied to individual files.

Tagging Releases in Subversion

The tags directory is there to hold marked versions of your project, such as “release-1.0” or “demo-iteration-2”. By tagging a snapshot of your trunk you basically “save” (create easy access to) the state of your project at that point, and then development can continue in the trunk.

The basic operation of tagging is described here: http://svnbook.red-bean.com/en/1.6/svn.branchmerge.tags.html

It is basically a “server-side” copy operation – nothing is actually copied, it’s just a virtual or logical copy.

The example in the RedBean book is basically correct, except that our server is not using HTTP, it is using SVN as a protocol. So the repo URLs would look like “svn://anonymous.cs.nmsu.edu/cs371f2013/team-name/trunk”.

Another Viewpoint: Using Subversion

This page is a description of using Subversion in class and for assignments in particular, it is not an entire introduction to Subversion.

If you know little to nothing about software repositories, how they work, and they expect you to work with them, you should read the first two chapters of the SVN book

Links to an external site. – but do not print it out on our departmental printers!

Even if you think you know a lot, the reading material above is still good.

Subversion is a tool that manages a source code repository (although it actually accepts any kind of file). Git is probably the most popular repository tool today, but Subversion is also popular and is easier to setup and maintain for a course. Developers, or any user of the repository, checkout a copy of the repository into their own files; this creates a local workspace. They then edit existing and/or add new files, and when they want their changes to be recorded in the repository, they commit the new content back into the repository.

Repositories keep and remember all content that has ever been committed to them! This includes files that have been “deleted” from forward-going versions! So once you commit, it is there until I destroy the repositories (and I don’t I keep them). So be careful! I once had a student commit the whole Eclipse IDE into an assignment, and I was very unhappy! I don’t even want your .class files!

Check out a new copy, creating a new workspace

The first step for a repository user is to create a new local workspace by checking out the repository. You can do this with the command

svn checkout svn://amon.cs.nmsu.edu/cs581spYYYY/yourusername

where YYYY is the current year (e.g., 2019) and “yourusername” is your CS username (not your NMSU username). This will ask you for a password; your password is your Aggie ID (the whole thing). You cannot change it, but this is enough security for this course – remember, all activities with a repository are logged, so if some student tries to be malicious to others, the repository will log it and we’ll figure it out.

The command line command “svn” is the Subversion command that is useable for all of the operations. Its first argument (here, “checkout”) is the particular operation that you want to do. If you are on your own system, there are GUI clients available for Subversion, but I recommend getting used to how the command line commands work, too.

After this command you have a new folder (directory) under whereever you ran the command, named “yourusername”. This is the root of your individual CS581 repository workspace. Yes it looks like a regular folder, but it is not! It is a workspace! You must use it as such, and never forget it.

You can check out as many workspaces as you want, on one machine (kinda silly) or on other machines (very useful). My whole work life is in subversion and I have workspaces on every computer I use. All I need to do is “svn update” and I’m all set to work on that machine!

Work in your new workspace

You can go into your workspace folder and work in it just like any other folder in your files. But always remember, it is a workspace. Typically, you’ll create a sub-folder in it for an assignment, and work on the assignment in there.

Tell Subversion to track new files and folders

When you are ready to commit changes to the repository, if you have any new files and/or folders, you have to tell Subversion to track them. Of course this will be true on your first commit, but it may be true later, as well. The command “svn status” or “svn st” (most Subversion operations can be abbreviated) will report to you the status of the files and folders in your current directory. If it says some sort of “not found” message, then you are too deep below anything known. If it says “? .” then it means the directory you are in isn’t even being tracked, and you should go up one directory (“cd .."). Otherwise, it will list the names of things in the current directory that are unknown (?) or are modified and not up to date in the repo (M).

Let’s say you created a directory “program1” and the command “svn status” says “? program1”. This means that it does not know about it and it is not being tracked by the repository. You need to use the “add” command:

svn add program1

But DON’T TRY THAT YET! The “add” operation tells Subversion to add this folder or file into the repository and begin tracking it. If you give it a folder name it will also add everything in the folder! And I don’t want your .class files to be added! So first be sure that ONLY source and text files exist in your “program1” directory, and then do the add (from the parent directory)

EVERY time you create new files or folders in your workspace that you want to have in your repository, you must use the “svn add” command. But always be careful! Also, it is perfectly fine to leave other files (like .class files) in directories that are already added; Subversion will just ignore them as long as you don’t add them, and they only get automatically added if you do an “svn add” on the folder containing them.

After doing the “svn add”, you can do “svn status” again and you’ll see the files listed with “A” that you added. They are NOT YET in the repository!

Commit the new files and any changes to the repository

Once you are in a state where you want the current state of your workspace to be recorded and saved in the repository, then you can do the command

svn commit -m 'A meaningful but short commit message here'

This command will send all the data of the new files and the data of any changed files to the repository, and the repository will store it as a saved state of those files. You will see some info about transmitting the data and then will see the message “Committed revision 437” (the number will change). When you see that message, you can know that your data is in the repository! If you don’t see it, it most likely did not work!

If you do not put the “-m ‘some message’ " on the command, it will automatically invoke some text editor such as “vi”, and if you do not know how to operate “vi” you will be stuck! So ALWAYS use the “-m” option with a message. The message must be in quotes if it has spaces in it; you should put a short (40 chars or less) message that is descriptive of what you are committing.

If things go wrong

If you get errors that you can’t seem to fix, search the web. There are operations such as “svn cleanup” and “svn revert” that can often get rid of errors. In the worst case, you can go somewhere else in your filespace, checkout another copy of the workspace, copy your changes over to it, add and commit them, and then delete the old workspace.

Collaborating with other people

Repositories are fine for single-person use to keep track of the history of work so that you don’t need to create backups, but they are really meant to support teams of people collaboratively working. The main Subversion operation to begin collaboration is

svn update

This pulls changes to a repository that other people made into your workspace. And when you commit and then they do an update, they get your changes! So on a team, do lots of commits and lots of updates!

Sometimes multi-person changes can conflict, and Subversion usually recognizes this and flags it. You’ll have to read elsewhere to learn how to handle this. For more complicated work processes, Subversion supports branching and merging and other things that help track a large project and help team members manage their collaborative work, but again, you’ll have to read about that elsewhere.