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 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.

The motivation for us to use version control in CS 2800 is that most homeworks will indeed be done in teams, usually of two people. Using version control, you can work on these mostly independently, whenever and wherever you are, as long as you have access to the Internet. Another good reason for using this in class is that virtually all large software development in industry is done using a version control system. Knowing this from one of your classes will be a valuable asset for the future.

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. A full documentation for subversion is available here. This 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 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. We have already created this repository for this class. Here is the typical work cycle for you:

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 don't need Internet access while you are working on your local copy). Using svn, you would type:

    svn checkout svn://chien.ccs.neu.edu/logicandcomputation/Homework/<xx>/<username>

where <xx> is the number of the homework, written as 01, 02, ..., and <username> is your username, 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 (also on Blackboard), and any comments the graders may have for you. Subdirectories 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).

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 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, check 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 the others to see. On the other hand, only do this once the code you have written is reasonably clean. Never commit any changes that contain syntax errors; this is very 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.

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 occassion:
    svn status | log | diff