CSC 307 SVN Basics

CSC 307 SVN Basics

SVN, aka, "Subversion", is a version control tool. Subversion is the latest in a long line of such tools, which have included CVS ("Concurrent Versioning System"), RCS ("Revision Control System"), and SCCS ("Source Code Control System"). Subversion is operationally very similar to its predecessors, and is generally acknowledged to be an improvement on all of them. There is also what many believe is the successor to SVN, called "git". We're using SVN in 307 ad 309 because it's still quite viable, it's a bit easier to understand than git, and it is very well suited to the medium-scale projects we're working on. When you learn the underlying concepts of SVN, what you learn will be applicable to just about any other version control system.

Subversion maintains a version repository that records the history of a project's files. Members of a project team each maintain an individual working directory. The working directory contains files that each member is in charge of, plus copies of files that other members are in charge of.

There are two fundamental operations in any version control system:

file check in, from a individual working directory to the repository
file check out, from the repository to a working directory

In subversion, check in is accomplished using the svn add and svn commit commands. Check out is done most frequently with the svn update command.

Listed below are specific steps for setting up and maintaining a subversion repository. The steps cover initial creation of the repository, checking in, checking out, and other useful commands. There are a good deal more subversion commands than those listed below. For CSC 307, these basics should be most, if not all of what you need. Further documentation on subversion is available online in the 307 documentation directory.

NOTE: When running the commands below, substitute the user ID of your team's librarian where the italicized librarian appears.

0. A Necessary UNIX Setting

Running on a CSL UNIX machine, use a UNIX editor to add the following line to the end of your shell initialization file (~/.bashrc or ~/.cshrc):

umask 022

then run the UNIX command "source ~/.bashrc" (or "source ~/.cshrc").

1. Initial library setup, in the librarian's projects directory (one time only)

cd ~
mkdir projects
mkdir www
cd www
ln -s ../projects .
cd ../projects
mkdir SVN
mkdir work
mkdir alpha
svnadmin create SVN
cd work
mkdir testtool
cd testtool
~gfisher/classes/307/admin/mkdirs.csh
cd ..
svn import testtool file:///home/librarian/projects/SVN/testtool -m "initial import"
rm -rf testtool
svn checkout file:///home/librarian/projects/SVN/testtool/trunk testtool
cd ~
chmod a+rx .
chmod a+rx www
chmod -R a+rX projects
chmod -R g+w projects/SVN

2. Initial project checkout, from repository to individual team member directories (one time only)

cd ~
mkdir work
mkdir www
cd work
svn checkout file:///home/librarian/projects/SVN/testtool/trunk testtool
cd ~/www
ln -s ../work/testtool .
cp ~gfisher/www/.htaccess .
chmod a+r .htaccess
cd ~
chmod a+rx .
chmod a+rx www
chmod -R a+rX work

3. Check in new work, from individual team member directory to repository

cd ~/work/testtool/...
create some-file
svn add some-file
svn commit -m "log message" some-file

4. Check in revised work, from individual team member directory to repository

cd ~/work/testtool/...
edit some-file
svn commit -m "log message" some-file

5. Check out other team members' work, from repository to individual directory

cd ~/work/testtool
svn update

6. Release (by librarian) of team members work, from repository to projects/work directory

cd ~librarian/projects/work/testtool
svn update

7. Removing previous checked in files

To remove a file X that is already in the repository, do the following:

svn remove X
svn commit -m "..."  X

This will both remove the file from your working directory and schedule it for removal from the repository. The svn commit, as with add, will actually commit the removal.

8. Viewing the status of individual work files compared to the repository

You can get a short form file status list as follows:

cd ~/work/testtool
svn status -u

This will print a list of files in your work directory that differ from the repository. This is the same list printed by svn update. Each listed file is preceded by one or more single-character status codes. The most important codes are the following:

Code Meaning
M You have modified the file since the last time you checked it in. Use svn commit to update the repository from your file.
? You have created a new file that is not yet in the repository. Use svn add and svn commit to add your file to the repository.
! You have deleted a committed file without removing it from the repository. Use svn update to get the file back.
A You have added a file (via svn add) but not yet committed it. Use svn commit to commit it to the repository.
R You have removed a file (via svn remove) but not yet committed the removal. Use svn commit to commit the removal from the repository.
* Someone else has modified the file and checked it into the repository. Use svn update to get the latest committed version.

If both an 'M' and an '*' appear with a file, it means that you have modified that file in conflict with another team member that has already committed a modified version. This case should never happen, if you follow the CSC 307 convention that only one person checks in a given file. If it does happen, see "Dealing with a Conflict" below.

9. Differencing Modified Files with Most-Recently Committed Versions

You can get a detailed comparison of a your working copy of a file and the most-recently committed version using the following command:

svn diff X

for any file X that exists in the repository. The differences are reported in a reasonably intuitive format, showing the changes that have been made.

10. Viewing a Log Report

Subversion maintains a complete log of all repository activity. To view the log for the project, do the following:

cd ~/work/testtool
svn log

This will output a list of log messages for all operations performed on the repository. The output includes who performed the operation and when it was performed. The "-v" option will output a more verbose log, which includes the names of all affected files.

To view the log for a project subdirectory, go to that directory and run "svn log". To view the log for a particular file X, provide the file name as an argument, i.e.,

svn log X

11. Undoing Working Changes

If you add or remove a file before committing it, you can undo the add or remove operation using

svn revert X

where X is the added or removed file. You can also use svn revert to erase any local changes you've made to a file before you've committed them.

12. Dealing with a Conflict

As noted above, a conflict means that someone else edited a file and checked it in, at the same time you were editing the file as well. The best way to deal with conflicts is not to let them happen in the first place. That is, observe the rule that one person owns a file and only that person should edit that file. If someone needs to edit a file owned by someone else, the would-be editor should contact the owner and confirm that the editing can be performed and committed.

You can detect if a conflict would occur without having a conflicted file being created. To do so, run "svn status -u" before you run "svn update". As noted above in item 8 , any files in the status list with both an 'M' and an '*' next to their names are files where your modifications conflict with modifications already made and committed by someone else.

If you detect such a conflict for a file X, you can do the following:

mv X X.sav
svn update X

At this point you compare X with X.sav to see what differences there are and how to deal with the differences. If it turns out that the updated file X is the correct version, then simply delete X.sav. If on the other hand X.sav is the correct version, then delete X and commit X.sav. If both X and X.sav have valid information, then you must create the appropriate new version based on the desired contents of both files, delete the old version and commit the new one.

Another way to deal with a conflict is to proceed with the "svn update", without resolving the conflict before hand. When you do this, svn will create three additional files named X.mine, X.ri, and X.rj, where i and j are old and new version numbers. Once these files are created, you examine each of them to determine which changes are valid. Then create the correct version of X, remove the other three files, and re-commit X.

A third way to deal with conflicts is to use the svn resolve command, after the status check, but before the update. For a conflicted file X, do the following:

svn resolve --accept version X

where version is one of the following:

base -- Choose the file that was the BASE revision before you updated your working copy. That is, the file that you checked out before you made your latest edits.
working -- Assuming that you've manually handled the conflict resolution, choose the version of the file as it currently stands in your working copy.

If you want to resolve conflicts for multiple files all in the same way, you can use these values of version in the svn resolve command:

mine-full -- Resolve all conflicted files with copies of the files as they stood immediately before you ran svn update.
theirs-full -- Resolve all conflicted files with copies of the files that were fetched from the server when you ran svn update.

13. Telling subversion to ignore certain files, such as binary executables

Within the directory where the files to be ignored reside, add the names of the files to a .svnignore file, then run the following commands:

svn propset svn:ignore -F .svnignore .
svn add .svnignore ; svn commit -m "Ignored files ..." .svnignore
svn update
svn commit -m "Added svn:ignore prop, with file .svnignore" .

The listed file names can include UNIX-style patterns, e.g., '*.o'. You can ignore the .svnignore file by including its own name in itself.

14. Connecting to a subversion server remotely

If you're running on a remote machine with subversion installed, you checkout a project remotely as follows:

svn checkout svn+ssh://userid@unix3.csc.calpoly.edu/home/librarian/projects/SVN/testtool/trunk testtool

There are a number of GUI-based subversion client programs available for use on Windows, Mac, and UNIX. These include RapidSVN at rapidsvn.tigris.org and TortoiseSVN at tortoisesvn.tigris.org. There are also IDEs, such as eclipse, that provide built-in subversion support.

Code	Meaning
M	You have modified the file since the last time you checked it in. Use `svn commit` to update the repository from your file.
?	You have created a new file that is not yet in the repository. Use `svn add` and `svn commit` to add your file to the repository.
!	You have deleted a committed file without removing it from the repository. Use `svn update` to get the file back.
A	You have added a file (via `svn add`) but not yet committed it. Use `svn commit` to commit it to the repository.
R	You have removed a file (via `svn remove`) but not yet committed the removal. Use `svn commit` to commit the removal from the repository.
*	Someone else has modified the file and checked it into the repository. Use `svn update` to get the latest committed version.