Basic Version Control Usage

Overview

We will be using a version control system for managing the homework submissions.  Virtually all large software development in industry is done using a version control system today. The purpose is to allow a team of developers (who may reside across the world) to collaborate on a project that produces some sort of text data, typically code, or a text document such as Latex. Using version control, all developers can add, change, or delete any part of the text, at any time, without the need to reserve time slots where one of the developers has the right to make changes. The system will (mostly automatically) make sure that, if people work simultaneously on the same parts, any conflicts that may arise are resolved without losing data. In addition, version control keeps a record of all versions of the data the team generates over time (hence the name). Thus, accidental changes to the data can usually be rolled back.

In CS 2800, most homeworks will be done in teams, usually of two people. Using version control, each of you can work on these mostly independently, whenever and wherever you are, as long as you have access to the Internet.

Subversion

The version control system we will be using is called subversion. It is very powerful, but we need only a small set of features for this class. We illustrate these features below. A full documentation for subversion is available here. That website also contains a description of the basic concepts underlying version control.

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 CCIS 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. We have already created this repository for this class. Here is the work cycle, using Homework 1 as the running example:

1. Check out the repository

= create a local copy of the repository data on your machine. You will be working with that local copy (you need Internet access to check out the local copy, but not while you are working on it). Using svn, you type:

    svn checkout svn://login.ccs.neu.edu/cs2800f12/01/<ccis> --username <ccis>

where <ccis> is your CCIS login name. Yes, you need to supply this name twice: as part of the directory name, and as the argument to the --username flag. This command will prompt you for a password, which was emailed to you. After you enter these credentials, a directory <ccis-login> will be created; this is where your solutions for Homework 1 will reside (hence the 01 in the path above; this will change for every homework). Eventually there will be a subdirectory grade, which will contain your grade for this homework (also on Blackboard), and any comments the graders may have for you. Directories not containing your login name are off-limit for you (which should be enforced by access permissions; please let us know if that seems not to be the case).

Once the checkout is complete, enter the <ccis-login> directory that was just created. You can only add files under that directory.

2. Put files under version control

Presumably, if the repository is fresh, you now have created some files that you want to belong to the repository. You communicate this to svn by adding them, as follows:

    svn add <file>

Note that, for this command (and the following), you do not need to specify the repository name (unlike the case of checkout). The reason is that you run this command from the top-level directory of your local copy. Subversion stores the name of the repository in a hidden file.

The name add is a bit misleading: all this does is tell subversion that <file> should be put under version control. (You may have other local files that you need for your own work but should not be part of version control, such as private backup files.) svn add doesn't actually modify the repository until you commit, see next. It is a common error of novices to forget to add new files if they belong in the repository. Similarly, to delete a file from the repository you have to tell subversion to remove it from version control, using svn remove. To rename a file that is under version control, try out svn move.

3. Commit your changes

= merge whatever you have done locally into the repository. You should do this whenever you feel you have made changes that are worth for any collaborators (in later homeworks) to see. On the other hand, only do this once the code you have written is reasonably clean. Don't commit any changes that contain syntax errors; this is impolite to other repository users, since they will have to fix your errors.

    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 (see next), and then commit.

4. Update your local copy

= check if anybody has made any chances to the repository, and, if so, copy those changes to your local machine.

    svn update

You should do this frequently, because the longer you wait synchronizing with the work of others, the more likely you will run into conflicts (see next point).

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, as per 3.

These are only very basic examples of using subversion. Again, consult the help features of your subversion client for more information on the syntax. Also, here are three other commands that may be helpful on occasion:
    svn status | log | diff