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".
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.
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.
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.
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
If you want to see what's going on while you are in the middle of changes you can use:
svn status
to look at the current project status, compare versions, or roll back to a previous
version (respectively).
svn diff
svn revert
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!!).