School of Computer Science 1 Using Subversion in Computer Science Last modified July 28, 2006 Starting from semester two, the School is adopting the increasingly popular SVN system for management of student software projects. This will provide experience with a key software engineering competency use of software configuration management which will be of great practical benefit. This semester, SVN will be used in a range of courses. 1 Introduction A source control system is one which can manage the changes occurring to software as a project is worked on and developed. Such systems are very important because they allow more than one person to work on a single project. They also provide a complete history of all files, which allows the project to be backtracked and comparisons made with previous versions. Subversion (SVN) is a popular source control system which is freely available 1 SVN is a tool available for most popular operating systems which is able to keep track of multiple revisions of a project. It works by noticing the differences in a set of files. These files can be source code, documentation, or anything else related to a project. SVN allows developers to maintain control over a specific item, such as a source file, while changes are being made. When a developer has finished making changes to that file, it is committed to the system, and is available for use by other developers. All of the changes made to the file are recorded by SVN, which enables comparisons with different versions of that file to be made at any time. SVN provides facilities for a number of developers to simultaneously modify files in a project at any time. It is up to the SVN system to control the checking in process so that conflicting changes are managed. SVN only stores the differences between versions instead of every version of every file ever created. It also keeps a log of who, when, and why changes have been made to each file. It is very helpful for managing releases and controlling the concurrent editing of source files among multiple authors. SVN provides version control for a hierarchical collection of directories consisting of revision controlled files. These directories and files can then be combined to form an entire project. The flexibility offered by allowing many programmers to contribute to a project in a safe manner makes version control tools such as SVN very popular. However, even on a project with a single author such as a course assignment SVN can prove very useful. 1 see http://subversion.tigris.org/project packages.html.
School of Computer Science 2 The chief benefits to using SVN when attempting practical work are the ability to roll-back changes, perhaps after inadvertently introducing an error into the code, and the ability to manage working on the assignment from multiple computers. For example, SVN can help when working on writing code from the systems at University, and your own computer at home. 1.1 Repositories Every project managed by SVN is stored in a central repository. In the repository all of the files related to the project are kept, along with all of the change and history information. For your own projects, your repository will be stored in a location accessed by the URL: https://version-control.adelaide.edu.au/svn/a1xxxxxx/ where the string a1xxxxxx should be replaced by your username. Separate from the central repository, several different copies of the project files may exist in working directories. These files are said to be checked out from your repository ready to be worked on. Files inside your repository cannot be accessed directly. Rather, only files inside a working, checked out, copy should be modified. Checked out copies of a project can exist in different places on the same computer (for example in different user s home directories), or they may exist on separate computers. In this case, SVN communicates over the network to control the versions. The next section describes the basics required to get started with using SVN for course assignments. 2 Using SVN for course assignments Every assignment that will be used in conjunction with SVN will have its own unique key. The key will contain the name of the course, the year and semester, and the assignment name. For example, the first assignment for DSA in semester one could have the following key: dsa 05 s1 assign1. Every assignment sheet which describes the assignment will also specify the particular key. It is very important to get this key right in the commands in which you use it. When first starting an assignment, the very first step is to create an appropriate module in your SVN repository. To do that, you need to run the svn import command to import the starting files for the assignment into your repository. The general format of this command is (broken over two lines to fit in this document): svn import -m {message-string} {starting-files} https://version-control.adelaide.edu.au/svn/a1xxxxxx/{key} where: {message-string} is some message indicating what you are doing surrounded in double-quotes. Typically, {message-string} is something like "initial import".
School of Computer Science 3 {starting-files} is the name of a directory containing the starting files you have copied to your home directory for the assignment, for example: /users/students/a1xxxxxx/dsa/dsa 05 s1 assign1. {key} is the assignment key, for example dsa 05 s1 assign1. At the very least, the values of files {message-string}, {starting-files} and {key} for this command will be given in each assignment specification. Note that the svn import command will only create files in your repository not files that you can actually edit. Also note that the original files that you imported are not in a format that svn can work with directly. You should remove the files you just imported from your home directory. Following on from the previous example, you would type: rm -rf ~/dsa/dsa_05_s1_assign1 or, at the very least, move the files to a safe place where you won t touch them for the rest of the project. Now you have your starting files in the repository and the original copies deleted or at least stowed away somewhere else. Now to start working on the assignment you will need to check out the code from your repository. To do that, you first of all need to create a place to store the checked out files. For example, create /dsa/, and change to this directory. From there, run 2 : svn checkout https://version-control.adelaide.edu.au/svn/a1xxxxxx/dsa_05_s1_assign1 dsa_05_s1_assign1 This will create a directory inside the current directory containing all of the assignment files. You can now work on your assignment. You should regularly commit any changes you have made to the files back to your repository. Although you probably don t want to commit every single line that is changed, we suggest committing at least at the end of every work session. When committing changes back to the repository, SVN requires a short message describing the changes made. These messages can be used later when browsing the history of a particular file. An example of a commit is svn commit -m "a relevant comment describing changes made..." Note that this commit must be executed from within your working copy. Also note that, very occasionally, it may take up to two minutes for commit to take effect in the repository. For some assignments all you will need to do is work on assignment, committing regularly and, when you have finished, commit again (we will checkout the relevant files from your repository for marking after the due-date). However, for many assignments you will be expected to have your assignment marked (or checked) using the web based submission system found at: 2 Again, the command above is broken over two lines to fit in this document.
School of Computer Science 4 https://www.cs.adelaide.edu.au/for/students/automark/ When you use this mechanism the marking system will expect your files to be in a directory with a specific name in your repository. The instructions for each individual assignment will tell you what this directory will be. 3 Basic SVN commands There are only a handful of commonly used SVN commands. Each of them is described briefly below. 3.1 checkout This command will take a copy of a project, and create a working directory of all of the files. It should be used like this: svn checkout https://version-control.adelaide.edu.au/svn/a1xxxxxx/{key} {key} Of course, the required {key} directory must have already been created in your repository by running the svn import command. Once an assignment has been checked out, the files can be modified inside the working directory. 3.2 commit The commit command will cause any of changes made to any file in the current working directory to be saved in your repository. This means that they are now part of the latest version and are available to all other developers. When committing files, a short description may be given using the -m option (see above). If a description is not given with the -m option, then SVN will open an editor where one can be specified. By default, on UNIX systems, the editor is vi. Which editor is opened by SVN can be controlled by setting the SVN EDITOR environment variable. For example, if you prefer emacs to vi, you can put setenv SVN_EDITOR emacs for example in your.cshrc file. Note, very occasionally a commit may take one or two minutes to take effect in the repository even after the svn commit command has finished executing. 3.3 add By default, every new file that you create in a working directory is not automatically included in your repository. In fact, SVN will ignore any new files unless you explicitly let it know. This is achieved using the add command. Note that you will not need to add every file in your working copy to your repository. For example Java.class files do not need to be added because they are easily re-generated from the Java source files.
School of Computer Science 5 As an example of the use of svn add: if you create a new file, Something.java, as a new source file in your project, you must add it to your repository by doing svn add Something.java Be warned though that this will merely tell SVN about the existence of the file. It will not actually be put into your repository until the next commit. Usually you would want to follow the above add with a svn commit -m "Added a new java file implementing..." 3.4 log and status The commands log and status can be used to find out information about files currently in a repository. If you have forgotten if a file is in your repository or not, you can say svn status NotSure.java from a working directory, and the output will tell you if that file is in your repository or not. If it is not, you should use the add command as above. If the file is in your repository, you can say svn log NotSure.java which will show the current revision number, who and when commits where done, and the comments given for each revision. Note, it is worth typing: svn update prior to typing svn status or svn log to make sure that the changes from your most recent commit are shown. update is described next. 3.5 update Execute this command from within a working directory when you wish to update your local copies of source files with the latest versions from your repository. For example, from within the working directory dsa 05 s1 assign1, the command svn update will recursively update all files in the project. It is possible to update only a single file at a time, for example svn update afile.java will only get the latest version of that particular file. 3.6 diff Because SVN stores all of the revisions made to files, it is possible to compare two different versions of the same file. This is often very useful when wishing to go back and look at older visions in the hope of finding an introduced bug. When used by just giving a file name, like this svn diff afile.java
School of Computer Science 6 then SVN will show the differences between the file in the current working directory and the latest version checked into your repository. So the above will show any changes made to the file afile.java since it was last committed. To go back further, then the -r option can be used to specify a revision number of the file to check for differences. The appropriate revision number can be found by first doing a svn log on the file. To view all differences between version 11 of afile.java and its current contents, simply do svn diff -r 11 afile.java 4 Using SVN remotely One of the great benefits to using SVN is not only can it manage a number of people working on a project, it can also help when one person is working on a project from more than one computer. In this case, more than one working directory will exist on different computers. An example is working on a programming assignment from the University system, and also a machine at home. In this case, your home machine will need to have the svn program available. There are also downloadable versions of the svn client program, for most platforms, including Linux, MacOS, and Win32 on the main SVN site 3. Once you have the svn command installed on your machine the commands for accessing your repository are the same as in this document so far 4. 4.1 Viewing your files In this school, we have configured SVN to work through a web-server. One nice feature of this setup is that you can view your repository using a web-browser. So, for example, if you want to see the files in the dsa 05 s1 assign directory in your repository, and your username is a1111111 then you can type: https://version-control.adelaide.edu.au/svn/a1111111/dsa_05_s1_assign1 into your web-browser and you can navigate through your files. 4.2 Use update As a habit, it is a good idea to run svn update before you begin work on files and svn commit, at least, at the end of the session. Of course, it doesn t hurt to run these commands more often. Moreover, when you have more than one working copy of your assignment files running these commands becomes even more important. 3 Again, see http://subversion.tigris.org/project packages.html 4 The commands may behave slightly differently, for example the initial checkout will require you to log in to the machine using your Computer Science password.
School of Computer Science 7 4.3 Resolving conflicts Conflicts between versions of files happen sometimes when multiple users are working on a file or when you are working on a file in more than one location and you forget to use update at the beginning of your session or commit at the end. You usually first notice a conflict when you are not able to commit without first performing an update and the update highlights some conflicts. Conflicts are a normal but they ll need to be resolved by you before you can progress (you won t be able to commit until the conflict is resolved). The exact path you should take to resolve the conflict is highly dependent on the project you are working on but it will usually involve editing and removing some files. Detailed instructions on how to handle conflicts are given at: http://svnbook.red-bean.com/en/1.1/ch03s05.html#svn-ch-3-sect-5.4 4.4 Rescuing files If you have accidently deleted a file from your working copy but have not committed the delete then an svn update or a checkout of a new copy of the repository should fix the problem. If you have committed a delete you can get hold of an earlier snapshot of your project using the -d option with a checkout command. For example, if you want to recover an version of your project from an assignment ai 06 s1 assign6 from 4.00pm on the 17th of May, 2006. You can type: svn co -d "{200605171600}" https://version-control.adelaide.edu.au/svn/a1xxxxxx/ai_06_s1_assign6 ai_06_s1_assign6 Note the line above has been broken into two parts but you will need to keep it all on one line and, of course, you ll need to substitute your own username for a1xxxxxx. 5 More information More information about any of the SVN commands may be found by typing svn --help {command name} where {command name} is replaced by add, commit, etc. By typing svn --help-commands, a complete list of all the SVN commands is shown. There are many resources describing SVN on the web. The primary reference is: http://svnbook.red-bean.com/
School of Computer Science 8 which gives comprehensive coverage of SVN and its features 5. A detailed Frequently Asked Questions (FAQ) page is also available at: http://subversion.tigris.org/faq.html There is a very useful section, in chapter 3 which provides a guided tour of the basic work cycle. This document can be found at: http://svnbook.red-bean.com/en/1.1/ch03s05.html There are also several mailing lists for SVN enthusiasts and users encountering problems these can all be accessed through: http://subversion.tigris.org/servlets/projectmailinglistlist Rob Esser Darren Gawley Kevin Maciunas Brad Alexander 5 The section titled A Quick Start suggests each project is set up with branches, tags, and trunk subdirectories. While this is a very sensible way to work on long-running projects most Computer Science assignments will not require this setup. Instead the project directory for your assignment will contain just the files you would normally put in the trunk part of the repository.