CMPS183, Fall 2011, Section 01: Subversion Tutorial

Official Subversion Website

Official Subversion Documentation

This document assumes you are using Subversion on a UNIX (or UNIX derivative) machine. Windows users are on their own (see the official documentation for help).

Earlier in the quarter, we discussed how to create a new project using the DForge system. In the examples below, we will use the fictional group "The Sluggers".

Initial Setup

To start using your subversion directory, you must first check it out (even though there is probably nothing there yet): svn checkout http://svn.dforge.cse.ucsc.edu/the_sluggers This will create a working directory on your local machine (or CATS account). You will do all of your work here. It will also create a directory called .svn to store the subversion data files. If you make subdirectories, each one will have its own .svn directory. You should only have to enter the location of your repository (on dav.cse.ucsc.edu) when you do the initial checkout. From then on, subversion will know where to look for all its files.

Getting updates

Once you have started working, the first thing you should do before beginning work each day is update your working copy. This will allow you to get any changes that others in your group have made since the last time you worked. Its very important to keep your working copy up to date because this reduces the number (and magnitude) of merge conflicts you will have. The following command (issued from inside your working directory) will update to the latest copy of all files. svn update If you have made local changes to a file, it will not be overwritten.

Making changes

There's four operations you will normally perform to make changes to files (assuming no conflicts):

svn add
svn delete
svn move
svn copy

You will use add to add new files and directories, and delete to remove existing ones. The move and copy commands are used more rarely. If you want to rename a file, you move it to its new name.

Committing Changes

Once you have finished making a set of changes, you can commit them back to the repository for the rest of your group to see: svn commit --message "Short description of changes" You might also choose to commit befor you are finished if someone else in your group needs to make a small change in the middle of your large changes (or vise versa). The --message "" part of the command is useful because it provides you and your group a history with the reasons each file was changed. For example, if someone says they will update a section, and you want to know if they did, you can look at the change log and (if they entered a message when they committed the changes) you will know if they did or not. To look the project's change log, use: svn log

Checking Status

If you want to see what's going on while you are in the middle of changes you can use:

svn status
svn diff
svn revert

to look at the current project status, compare versions, or roll back to a previous version (respectively).

When Changes Collide

You will have collisions. One person will edit a file in the same area(s) that another person has. The first person to commit their changes will have it easy... the other person will have to merge the changes in their local directory before they can commit. When you run the command svn update, files with a preceeding C have conflicts that cannot be automatically handled by subversion (files with a preceeding G had local and remote changes, but they did not conflict and subversion handled the merge automatically).

When there is a merge conflict, subversion will put conflict markers into the file to show you the problem areas. It will also place three files into your working directory:


filename.*.mine

The file as it was before you tried to update. There will be no conflict markers here.

filename.*.rOLDREV

The file as it was before you started to make changes.

filename.*.rNEWREV

The file that is currently checked in with changes that conflict with yours.

 

To fix the conflict and check your changes in, you must edit the working copy (the file without any of the special extensions listed above), or replace it with on of the three files subversion generated. Note that replacing your working copy with the filename.*.rOLDREV file will effectively remove your changes and the other person's changes. After fixing the working copy, remove all three of the subversion generated files (filename.*.mine, filename.*.rOLDREV, and filename.*.rNEWREV). Once they are gone, you will be allowed to commit the changes.

When you edit the working copy of the file, you will find the conflict areas labeled with: <<<<<<< .mine where your changes are, ======= between your changes and the conflicting changes, and >>>>>>> .r2 where the conflicting changes end. Make sure you find and fix all sections tagged like this.

After you've made the changes, run: svn resolve filename to tell subversion that the conflict has been resolved (this step may remove the subversion generated files for you... I'm not sure). After that, you can try the commit operation again (and hopefully there haven't been more conflicting changes while you were fixing the last set!!).

Official Subversion Documentation that was used to create this page.