Basic Version Control Usage

Overview

We will be using a version control system for managing the homework submissions. As explained in class, the purpose of a version control system is to allow a team of developers (who may reside across the world) to collaborate on a project. Using version control, all developers can add, change, or delete any part of the text, at any time. The version control system will (mostly automatically) make sure that, if people work simultaneously on the same files, the changes they made are merged together. If the system cannot figure out how to merge changes, then a user has to manually resolve this conflict. In addition, version control keeps a record of all versions of the data the team generates over time (hence the name). This allows you to easily revert back to any previously committed version of the data.

Our motivation for using version control in CS 2800 is that most homeworks will be done in teams, usually of two people. Using version control, you can work independently, wherever you are, as long as you have access to the Internet. Another reason for using SVN is that virtually all large software development in industry is done using a version control system, so this is something you have to learn.

Subversion

The version control system we will be using is called subversion. It is very powerful, but fortunately we need only a small set of features for this class. We illustrate these features below. Subversion is fully documented in the Subversion book.

Please read the Subversion book up to the end of chapter 2. The book is well written and if you read up to the end of chapter 2, you will understand the basic usage model.

For this class, all you need is a subversion client. Subversion clients are available for free for Linux, Windows, and Mac; it does not matter which one you use. On the NEU CCS Windows computers, the GUI TortoiseSVN client should be installed. Some of these clients have a Gui, some of them are command-line based. For our illustration below we will be using the svn command to perform all our tasks. svn is the command-line interface to subversion available on Linux. It should be obvious which functionality this corresponds to in whatever client interface you are using. svn --help gives you svn specific details on command syntax.

Basic Steps For Working With Subversion

The homework submission data are stored in what is called a repository. For each homework assignment, you have to first create a local copy of the repository on your machine. Here is how to do this. Type:

svn checkout svn://dell-server-wahl-1.ccs.neu.edu/cs2800-2013-spring/<xx>/<username>

where <xx> is the number of the homework, written as 01, 02, ..., and <username> is your username or groupname, which will be emailed to you. This directory is where your solutions will reside. The further subdirectory grade will contain your grade for this homework (we will also enter the grade on Blackboard), and any comments the graders may have for you. Subdirectories not containing your login name are off-limit for you (which will be enforced by access permissions; please let us know if that seems not to be the case).

Once you checkout the repository, here is the typical work cycle for you:

1. Update Your copy of the Repository

Before making any modifications, make sure you have the latest version of the repository. Go to the directory containing the repository and type:

svn update

If you forget to do this, it makes conflicts more likely (see below).

2. Work on Your Homework

Next, you work on your homework.

3. Commit your changes

You should commit every time you modify your homework. Make sure that the code you have written is reasonably clean and free of syntax errors. It is very impolite to other repository users to commit files with errors since they will have to fix your errors if they want to make any progress.

First, check to see if you created new files that you want to add to the repository. If you did, you have to add the files to the repository, as follows:

svn add <file>

The name add is a bit misleading: all this does is tell subversion that <file> should be put under version control. You only have to do this once because once a file is under version control, it remains under version control. It is a common error of novices to forget to add new files if they want the files to be part of the repository. The reason why subversion requires that you explicitly add files to the repository is that you can have files that are in the same directory, but that you don't want to put under version control (e.g., a file with notes intended only for your use). By the way, to delete a file from the repository you have to tell subversion to remove it from version control, using svn remove. See the subversion book for details.

svn add doesn't modify the repository. To commit your changes type:

svn commit -m "comment on what I have done"

Committing changes only works if no-one else has committed anything to the repository in the meantime. If someone has, subversion will require you to update your local copy first, and then commit. Alas, it is also posssible that there is a conflict, a topic we discuss next.

5. Resolve Conflicts

Subversion will generate an error if an attempted update requires modifications to parts of the data that you have also modified (since your last commit). In that case, it will report to you which files are in conflict, and also create tags inside those files that highlight the conflicts. You need to resolve those manually (perhaps by communicating with the other developer who made those changes). Once resolved, you need to remove those tags from the file and tell subversion that the conflicts have been resolved:

svn resolved <file>

Now you should be able to commit your changes.

These are only very basic examples of using subversion. Again, consult the subversion book and the help features of your subversion client for more information.

Finally, here are three other commands that may be helpful on occassion:

svn status | log | diff