How to use the SVN archive

• SVN! aka, Subversion!

• The SVN repository is set up in  /cvs/cds/caltech/svn. Do not try to modify it or put anything on the directory. It is the job of svn command. An apache web server dedicated to handle svn queries is running on nodus.

Table of Contents

BR

Using SVN in the control room

• You can access the svn repository from the control room computers by something like svn co file:///cvs/cds/caltech/svn/trunk/. However, it is strongly discouraged to do so unless you are absolutely sure about what you are doing. Use the method below even from the control room computers.

BR

Uploading a New Directory to the Repository

• The command svn import will take a local directory and move its contents (not the directory itself, though) to a specified directory in the repository. It is to be run on files that are not yet in the repository (not for updating files that already are). For example:

• svn import --username svn40m ./test https://nodus.ligo.caltech.edu:30889/svn/trunk/docs/Test -m "Notes regarding the import go here."

• will take everything in the local directory ./test and copy it into the repository under the path https://nodus.ligo.caltech.edu:30889/svn/trunk/docs/Test. If the path in the repository does not exit, it will create the necessary directories.

• The import command does not set the new directory up for editing; i.e., commands like add, commit, update, etc. will not work. In order to set up the local system for working with these commands, the checkout command must be used (described below).

• Note: svn import copies the contents of the local file, not the file itself. Thus,

•  svn import --username svn40m ./test https://nodus.ligo.caltech.edu:30889/svn/trunk/docs/ 

• will put the contents of ./test (not ./test itself) in the folder docs, which may not be desired.

• Another Note: As with commit, import requires the -m flag and a following blurb of texting describing the import.

BR

Getting files from off-site

• The command svn checkout (or svn co) copies a directory from the repository to the local computer. It will also set-up the newly created local directory for use with commands such as add, commit, etc. For example:

• svn checkout --username svn40m https://nodus.ligo.caltech.edu:30889/svn/trunk/docs/Test/ ./workingCopy-test 

• will copy the contents of https://nodus.ligo.caltech.edu:30889/svn/trunk/docs/Test/ and to the path ./workingCopy-test. If the required path does not exist, it will create the required directories. It also creates a .svn file inside ./workingCopy-test and every sub-directory of ./workingCopy-test. It is this file that allows commands like add and commit to work. If you want to check out an older version of a directory, use the flag -r followed by the desired version number.

• Note: Like import, check out copies the contents of a directory, not the directory itself. Be careful you don't copy one directory too shallow.

• Another Note: The command

• svn checkout svn+ssh://controls@nodus.ligo.caltech.edu/cvs/cds/caltech/svn/trunk/Test/ ./workingCopy-test

• also works, though it should be avoided in favor of the previous method whenever possible.

BR

Adding and Committing Files

• The svn commit will upload modifications of a local file to the repository, provided that the repository already 'knows about' the file. It can only be successfully run in a directory that has been set-up for svn (see checkout above). For example, if the repository already contains the file test

• svn commit test -m 'Notes for the update to test'

• will upload the new version of 'test' onto the svn server. The command returns the version number of the update. Files that are 'known about' automatically includes anything checked-out with svn checkout. Other files need to be added manually, as described below. If you attempt to commit something that isn't known, svn with throw an error along the lines of "'filename' not under version control

• Note: svn commit will not work without the -m flag and a comment regarding the update. If you try to commit without a comment, svn will attempt to open a text editor (likely emacs), which will probably fail. Thus, if your getting strange errors regarding emacs, make sure you're including a comment.

• Another Note: If the file on the server is different than than the base file (i.e., before you made changes) that you are committing, the commit will fail. This can happen if someone else committed a change to the file that you did not receive. See 'updating' below on how to solve this problem.

• If you have recently created a new file, the svn system does not 'know about' it, and svn commit will not work. In order to add the new file to the svn system, use

• svn add filename

• While svn add 'teaches' the system about the new file, it does not actually upload the file itself. svn commit must be run after svn add to do this. Thus, if you recently created the file test2.txt and want to add it to the svn system, run

• svn add test2.txt

• and then

• svn commit test2.txt -m 'Notes regarding test2.txt'

BR

Other Commands for Manipulating Files

• Svn has its own versions of the standard bash commands mkdir, rmdir, cp, rm, and mv. These are svn mkdir, svn rmdir, svn cp, svn delete, and svn mv respectively. These act identically to their bash equivalents, except that they also tell the svn system about the changes that have been made. In any directory that has svn control (e.g. any directory created with svn checkout), you should use the svn versions of these commands instead of the regular ones. If you don't, svn commit will likely stop working for the files that have been changed, since the svn system will not 'know' about the file's new name or new location.

• None of these commands actually update the files on the svn server. In order to upload the change, you should run svn commit on all affected filenames, including those that have been deleted. For example, if you wanted to rename the file test1.txt to test2.txt, you would first run

• svn mv test1.txt test2.txt

• to rename the file locally and tell svn about the name change. This would be followed by

• svn commit test1.txt -m 'Notes about the change'

• and

• svn commit test2.txt -m 'Notes about the change'

• The first command will upload the new (i.e., now non-existent) file test1.txt to the svn server, effectively deleting it. The second will upload the new file test2.txt, creating it on the svn server.

• These svn commands can also be used to affect files on the svn server directly. This is generally a poor idea: it is usually better to make any changes locally and let svn commit transfer the changes onto the server. If the structure of the svn server needs to be changed in a way that cannot be done with svn commit, these commands allow you to do it. In order to affect a server file, simply give its direct name on the server to the svn command (you'll also need to pass the username flag). For instance, to create the directory 'testdir' under 'trunk/', call

• svn mkdir --username svn40m https://nodus.ligo.caltech.edu:30889/svn/trunk/testdir

• This can be useful if you wish to start a new, svn-controlled project that does not have any files associated with it (i.e., svn import isn't useful). In this case, you can create the location of the new project on the server with the above command and then use svn checkout to create an svn-controlled local copy of the directory to begin working in.

BR

Updating and Reverting Local Files from the Server Files

• If there is more than one person working on a project and updating to an svn server, it is possible that version of a file on the svn server is more recent than the your local version (i.e., someone else committed a change to the file). In order to update your local file, run svn update. This will modify your local file so that it is up-to date with the most recent version of the file. If you have made changes to your local file, svn will attempt to merge the two files. I don't really understand how this works.

• If you have made changes to a local file that you don't wish to keep, the svn revert command will remove any local changes made to the file.

BR

A sample session

Task: Making your own directory under trunk/docs/ and put a draft of your potentially Nobel prize winning paper.

(1) Make your own directory in the repository.

• svn mkdir  --username svn40m https://nodus.ligo.caltech.edu:30889/svn/trunk/docs/mydir

• At this point you may get an error along the lines of:

• svn: Could not use external editor to fetch log message; consider setting the $SVN_EDITOR environment variable or using the --message (-m) or --file (-F) options 
  svn: None of the environment variables SVN_EDITOR, VISUAL or EDITOR are set, and no 'editor-cmd' run-time configuration option was found

• if that happens try adding the -m "Comment" option. Like so:

• svn mkdir  --username svn40m https://nodus.ligo.caltech.edu:30889/svn/trunk/docs/mydir -m "A new directory which is mine, all mine!"

(2) Check out the directory you just created to your machine.

• svn co  --username svn40m https://nodus.ligo.caltech.edu:30889/svn/trunk/docs/mydir

(3) Move to the checked out directory.

• cd mydir

(4) Put your draft into the directory.

• cp /somewhere/ProofOfEverything.tex . 

(5) Put the file under the svn's control.

• svn add ProofOfEverything.tex

(6) Check it in to the svn repository.

• svn ci -m "The first draft"

• You have to put your comment after -m

(7) Update your working copy.

• svn up

(8) Now delete the file from the repository because you realized it is totally bullshit.

• svn delete ProofOfEverything.tex
  svn ci -m "Oops, I was wrong"

• However, your crappy paper can still be retrieved from the repository by requesting an old version, because all the history is recorded in the svn world.

BR

SVN clients

Windows

• TortoiseSVN [http://tortoisesvn.tigris.org/]

Mac OSX

• commandline - svn is included in the standard installatio of Mac OSX.

• svnX - [http://code.google.com/p/svnx/]

  BR BR

Links

• [#TOP back to the page top]

• back to How to

• http://svnbook.red-bean.com/ for more information about svn