CSC 309 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.

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:

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 308, these basics should be most, if not all of what you need. Further documentation on subversion is available online in the 308 documentation directory.

NOTE: When running the commands below, substitute the user ID of your team's librarian where the italicized librarian appears. Also, substitute your team's project ID where the italicized your-project appears. The project IDs are cstutor, eclass, grader, scheduler, and testtool. Please use all lowercase and no other punctuation in the project IDs.

0. A Necessary UNIX Setting

In a UNIX editor, 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)

For 309 librarians who continue their jobs from 308, this set-up step is not necessary. For new librarians or new projects, this step will import from the project identified by your team as the base spec. The italicized directory name base-spec-project refers to the root directory of the project to be imported. New librarians, i.e., you were not a 308 librarian, should perform all steps, ignoring any messages about creating existing directories. Continuing librarians with new projects, i.e., you were a 308 librarian for a different project, can skip to the "cp -rp" step.

cd ~
mkdir projects
mkdir www
cd www
ln -s ../projects .
cd ../projects
mkdir SVN
mkdir work
mkdir alpha
svnadmin create SVN
cd work
rsync -rptluv -e ssh --exclude .svn --exclude CVS base-spec-project .
svn import your-project file:///home/librarian/projects/SVN/your-project -m "initial import"
rm -rf your-project
svn checkout file:///home/librarian/projects/SVN/your-project/trunk your-project
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/your-project/trunk your-project
cd ~/www
ln -s ../work/your-project .
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/your-project/...
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/your-project/...
edit some-file
svn commit -m "log message" some-file

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

cd ~/work/your-project
svn update

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

cd ~librarian/projects/work/your-project
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/your-project
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 308 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/your-project
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.

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 commit -m "Ignored files ..."
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/your-project/trunk your-project

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.




index | lectures | handouts | examples | doc | lib | grades