SVN Tutorial

​Subversion (or SVN) has a number of different subcommands that allow you to perform different actions on the repository and on your copy of the code. For a complete listing of these commands, type

svn help

For information on a particular subcommand, type

svn help subcommand

The commands and descriptions given here are presented approximately in the order in which a user is expected to need them. This is why Checking In is discussed much later than Checking Out.

Note: for all of the commands below, it is assumed you are operating in the base directory for a given module. I.e., if you're going to checkout something to the "bearclaw_revision_173" directory, it is assumed you've made the directory and are currently sitting in it.

Checking Out Code

The first thing you are likely to be doing with SVN is downloading or "checking out" a copy of the code. To do this, type the following svn co command, where [username] refers to a valid user on the file server:

svn co svn+ssh://[username]@clover.pas.rochester.edu/var/repositories/astrobear/dev astrobear
svn co svn+ssh://[username]@clover.pas.rochester.edu/var/repositories/bear2fix/dev bear2fix

This checks out a copy of the AstroBEAR code and the bear2fix utility, using CURRENT_DIR/astrobear and CURRENT_DIR/bear2fix as the respective target directories. A different directory may be supplied as an optional argument. Note that whatever path you choose should be reflected in the $BEARCLAW environmental variable in ~/.bashrc.

This initial checkout will create a directory tree that should be complete and nearly ready to be ​compiled. After this initial checkout, you should only need to update your working version (see below) rather than checkout the entire code again.

You may also checkout a revision other than the current one, via

 svn co -r N https://[path] [optional_directory]

where N is any number from 1 to the current revision number and [path] stands for one of the repository paths above.

Browsing the Repository

Bearclaw/astroBEAR

To navigate the repository, use Trac's ​Source Browser at the top of every Wiki page.

bear2fix

The post-processing tool bear2fix also has a ​Source Browser.

Querying the Working Copy Version

To quickly find out the revision number of the working copy,

 svn info

Updating a Working Copy

To make your working copy up-to-date to the most recent version of the code,

 svn up

or

 svn update

This will cleanly update only files you have not modified, though it will also add back files you've non-SVN'ly deleted. However, if changes have been made to a file, it will try to merge the changes with the unmodified file in the repository. If it is unsuccessful, it will report a version conflict that you will have to resolve.

The update command is an extremely useful one, because it also lets you select a different version of your code. This allows you to roll back to a previous version if someone else has introduced a change that has broken your code. The version-selection command is

svn update --revision=REV_NUMBER

where REV_NUMBER is the target revision number. Note that this command can also result in version conflicts if changes you have made to the code conflict with an earlier version.

Querying Changes made to the Working Copy

To see what files you've made changes to/left alone/deleted/etc. from the version which you checked out, do:

 svn st -v

This returns a verbose list of files and flags:

Flag	Interpretation
?	File is not part of SVN—see how to add files below.
!	File is missing or incomplete (moved/deleted without involving SVN)
M	File has been modified by you.
none	File is the same as when it was checked out.

To see if your copy of the code is up-to-date, or, to see how your modifications compare to the current repository version,

 svn st -u

Note that this command, as well as most others, may be performed on the entire working copy structure (as in the above) or on a single file, e.g.

 svn st -u file.f90

will tell you whether file.f90 is up to date versus the most recent revision. Note also that if you delete a directory with (svn rm {directory} ) or without (rm {directory} ) involving SVN, doing svn st -u will list every file in that directory, pointing out that each has been deleted. To avoid this, you may do

 svn st -uq

to have it quietly list changes. In the case of deleting a directory, it will list only that it has been deleted, without detailing the deletion of each file.

Saving Your Work To The Repository

If you have modified existing files (rather than added/deleted — see below) and are sure that they work, you are can check in these changes so that other people can benefit by doing:

svn ci

or

svn ci -mCHECK_IN_DETAILS

Where CHECK_IN_DETAILS is a quote-enclosed string detailing the changes in the current version. Typically, only a short message is required when checking in something to the repository, e.g. "Fixed _ module." If the environmental variable $EDITOR or $SVN_EDITOR is set (e.g., in ~/.bashrc, set export SVN_EDITOR=nano), typing simply svn ci will allow you to give more complicated details in the text editor of your choice.

Adding/ Moving/ Deleting Files in SVN

If you plan on committing any change other than modifying an existing file — moving files, deleting files, adding files, etc. — you must do the changes within SVN in order for it to recognize them. This lets SVN know that it needs to update the repository's internal file structure. This involves simply prepending the usual command with svn, e.g.

 svn rm badfile.f90

will remove badfile.f90 within SVN's structure so that when you check-in, that file will no longer exist in the revision. If you simply rm badfile.f90, badfile.f90 will remain in the revision, even after you enter the check-in command. The SVN repository will think the file has just vanished; consequently, the next update will restore badfile.f90.

As for another example, if, you were to add newfile.f90, you would need to type:

svn add newfile.f90

otherwise SVN would not include the file in the repository.

Other commands include: svn move, svn delete, etc.

Note that all of these options will increment the revision by 1. This is why it's good to use the -m option to comment your changes—when the code breaks and you need to know what each of the last five or six revisions did, the time you save may be your own.

SVN Quick Reference Card

For other symbols, and a list of SVN commands with short descriptions, please see the SVN Reference Card (​SVN mirror).