SVN or Subversion is a source code management system (also called a version control system). It is a tool that allows a group of programmers to work together on the same collection of source files without getting in each others' way any more than necessary. It also helps track of the change history of the files and makes it possible to examine the way things looked at arbitrary times in the past.
In this course, you will be modifying a large body of code and you will be working with one or two other people on most of the assignments. Furthermore, we will be adding starter code to your system before each new assignment. The only sensible way to manage all of this is to use some sort of tool.
Source management tools are used almost universally in industry and open source projects. So by learning to use Subversion effectively in CSC369, you will not only have fewer headaches in trying to keep your work organized, but you will also be learning a useful skill to take with you when you complete your undergraduate CS education.
The version control model assumes that there is one central official master copy of everything. It is called "the Subversion repository." This copy is managed by Subversion and cannot be touched directly.
When you wish to work on a SVN-managed project, you "check out" your own private copy. Since work on a program is an ongoing process, and other people may be working on the same program at the same time, you need to make sure that your working copy stays up to date with the copy in the repository. You must explicitly "update" your copy when the master copy changes.
When you transfer ("commit") changes in your private copy to the master copy, the master copy is updated and other developers will then see those changes when they update. Changes you make in your private copy will not be seen by anyone else until you commit them. Commit early and commit often! Whenever possible, try to commit your changes as soon as you have a small piece working.
You can have as many private copies. Usually, you will have only one on each of the different machines you use. Circumstances may arise in which it is more convenient to have two, or to make temporary ones, or whatever. Just remember that they are all independent: while they're all connected back to the master copy, they are not connected to each other except through the master copy.
The repository is the official master copy. We are managing the Subversion repositories so that you do not have any direct access to the files in the repository. The only way you can get at the files is through svn commands.
Subversion's numbering scheme differs from CVS in that CVS uses file-specific numbering for revisions, and Subversion applies a revision number to the whole repository. So each commit to the repository increments the version number. Subversion's numbering scheme makes it easier to revert to a previous version if necessary (see below).
Under the Subversion (and CVS) model, it is possible for two people to edit the same file. When you go to commit your changes, if the current version of the repository does not match the version of your local copy, you will be forced to do an update before you can commit your changes.
When you update, SVN noticed that you have changed your copy and the master copy has also changed. SVN tries to merge the two sets of changes. If the changes are to unrelated areas of the file, this usually succeeds. If the changes overlap, or the merge program gets confused, SVN will say "Commit failed: Out of date..."
Look carefully at the output of the update command. you will see a list of files with a single letter at the front. If you see the letter "C" that means that there was a conflict when Subversion tried to merge changes in the file. The file will contain blocks that look like this
int foo(void) {
<<<<<<< .mine
bar();
=======
baz()
>>>>>>> .r6
}
This means that your copy of the file changed function foo to call bar, but the official copy in version 6 changed foo in the same place so it calls baz.
When you get conflicts like this, you need to resolve them before committing your new versions. You need to edit the file and decide which version to choose.
Subversion also saves a copy of each version of the file when a conflict arises, with extensions .mine, .r1, .r2, etc. These files can be used to help fix the conflict.
When you have resolved the conflict, run "svn resolved <file name>" and then commit your changed. Alternatively, you can remove the extra files and then run commit.
Merging big changes can be painful and time consuming. Update early and often, and commit early and often. Every time you sit down to do some work, you should run update to make sure you have all the changes made by your teammates.
Then general rule for commits is that any changes should be committed as soon as you are reasonably certain that they are correct. This means that you will be well-served by adding one feature, compile and test it (I'm not kidding). Then commit that code before working on the next feature. This will help minimize the number of conflicts you are likely to encounter.
Ideally you and your partner should keep track of which tests you expect to work at any particular time, and before committing check to make sure that they all still do work.
In most cases, one should try to avoid committing changes that cause the program to stop working properly (or, even, stop compiling at all.) This rule can sometimes be profitably bent when you know your partner will not be affected by the errors introduced.
Commit any files that cannot be automatically regenerated. Do not commit objectfiles or executable files. If you write extra code for tests, or experiments, commit that code.