SVN "quick reminders"

This is not intended to be an exhaustive discussion of SVN. For that, you should go to http://subversion.tigris.org/
If you are interested in an on-line book ... http://svnbook.red-bean.com/ is the place for you.
If you are interested in creating a tar file/ ...

Here is the definition of some terms I will use:
A repository is the master collection [of projects] and is actually a database.
A project is a collection of related files.
A sandbox is a project being edited.
working copy a two-word way of saying "sandbox".
The subversion client is the machine that will receive the files from the repository. Fundamentally, the machine that will have the sandbox.
The subversion server is the machine that has the repository. You will not be able to log in to the machine, nor should you be able to.

This www-page is almost exclusively from the perspective of someone who is using svn to READ from a repository someone else maintains. There is a section titled "For Those Who Can Write" that only applies to those who can write to the repository.

If you are getting checksum errors, you have probably modified one of the 'hidden' .svn files (the local backup copy), which you should not do. The following instructions on how to update your local backup copy are apparently simpler than the top hits on google - which involved recomputing the MD5 checksum and/or editing server files.

For Those Who Can Read from the repository

Hopefully, this should pertain to just about everybody. Minimally, you will need to have the subversion command-line client application svn installed on your machine. For the most part, the miracle of http takes care of the details of communicating with the server.

SVN ready-reference, optional items are [bracketed and in blue]

These are the most common subversion client commands, in my (limited) experience.
• checkout
• status
• log
• diff
• update
• add
• rename
• revert
• resolved
• switch

svn checkout [--revision HEAD] projectname [directoryname]

creates a working copy of the project for you to modify.

Example:

cd someplacenew;
svn checkout -r HEAD http://subversion.ucar.edu/DAReS/DART/trunk DART

As far as I can tell, the -r HEAD part is the default -OR- I get the same thing with or without it.
Note there are multiple ways of specifying the option. -r HEAD and --revision HEAD are the same.

Example 2: checking out a tagged version --
The easiest way to figure out what tagged versions are available is via the www-based interface, just point your browser to the 'tags' portion of the repository - http://subversion.ucar.edu/DAReS/DART/tags The www-page will have a list of all the tagged versions of the code. Let's say you want to check out the post_iceland version, which we'll put in a directory called post_iceland_DART.

svn checkout http://subversion.ucar.edu/DAReS/DART/tags/post_iceland post_iceland_DART

svn status [-u -v]

reports the changes to your working copy WITHOUT making any changes to your working copy.
With no args, print only locally modified items (no network access).
With -u, add working revision and server out-of-date information.
With -v, print full revision information on every item.

Example:
In this example, the working copies are unmodified. The repository has been updated, and some little bird told me to update. Here's what you could do ... commands I typed look like this.

[shad:~/svn/DART/mpi_utilities] thoar > svn status
[shad:~/svn/DART/mpi_utilities] thoar > svn status -v
             2528     2387 nancy        .
             2528     2387 nancy        mpi_utilities_mod.html
             2528     1974 nancy        mpi_utilities_mod.nml
             2528     2385 nancy        null_mpi_utilities_mod.f90
             2528     2302 nancy        mpi_utilities_mod.f90
[shad:~/svn/DART/mpi_utilities] thoar > svn status -u
       *     2528   mpi_utilities_mod.html
       *     2528   mpi_utilities_mod.nml
       *     2528   null_mpi_utilities_mod.f90
       *     2528   mpi_utilities_mod.f90
Status against revision:   2570
[shad:~/svn/DART/mpi_utilities] thoar > svn diff mpi_utilities_mod.f90
[shad:~/svn/DART/mpi_utilities] thoar > svn diff -r HEAD mpi_utilities_mod.f90
Index: mpi_utilities_mod.f90
===================================================================
--- mpi_utilities_mod.f90       (revision 2570)
+++ mpi_utilities_mod.f90       (working copy)
@@ -145,11 +145,9 @@
                           set_output
 use time_manager_mod, only : time_type, get_time, set_time
 
-! BUILD TIP
+!
 ! Some MPI installations have an MPI module; if one is present, use that.
-! (i.e. 'use mpi')
 ! If not, there will be an MPI include file which defines the parameters.
-! (i.e. 'include mpif.h')
 ! Use one but not both.  For help on compiling a module which uses MPI
 ! see the $DART/doc/mpi directory.
 

Property changes on: mpi_utilities_mod.f90
___________________________________________________________________
Name: svn:keywords
   - Date Author Revision HeadURL Id
   + Author Date Id Revision

svn log [--revision xxxx]

shows log message for the latest repository commit.

Example:

0[123] dart:~/SVN/DART/perfect_model_obs > svn log --revision 2510 perfect_model_obs.f90
------------------------------------------------------------------------
r2510 | jla | 2006-12-14 10:54:09 -0700 (Thu, 14 Dec 2006) | 3 lines

Changed time_index so that first time is always output for any
diagnostic output period.

------------------------------------------------------------------------
0[124] dart:~/SVN/DART/perfect_model_obs > svn log --revision 2510:2600 perfect_model_obs.f90
------------------------------------------------------------------------
r2510 | jla | 2006-12-14 10:54:09 -0700 (Thu, 14 Dec 2006) | 3 lines

Changed time_index so that first time is always output for any
diagnostic output period.

------------------------------------------------------------------------
r2565 | thoar | 2007-01-23 21:38:37 -0700 (Tue, 23 Jan 2007) | 2 lines

Turning on the svn propset svn:keywords "Date Author Revision HeadURL Id" 

------------------------------------------------------------------------

Example: A particularly useful syntax is to subsitute a (possibly unknown) revision number with a date:

0[125] dart:~/SVN/DART/perfect_model_obs > svn log --revision "{2007-04-13}":HEAD perfect_model_obs.f90
 ...you get the picture ...

Example: If you want to see the log and changed files for ALL repository changes (starts at the head and goes back as far as you're willing to read - this is helpful when determining "what's changed - lately"):

0[123] thunderbolt > svn log --v https://proxy.subversion.ucar.edu/DAReS/DART | less

Example: If you want to see what the log or the source of a deleted file, you need to get a version number from before the deletion. Once you know a version number, you can:

svn log https://blah.blah/repository_file.f90@1234

The @REV syntax can be used in a lot of places - not just on dead files. However, the '-r 1234' argument doesn't work with dead files, so you have to use the @REV syntax here.

svn diff [--revision HEAD]

The "svn diff" command produces output by comparing your working files agains the cached "pristine" copies within the .svn area. Fies scheduled for addition are displayed as added text, and files scheduled for deletion are displayed as deleted text. Output is displayed in "unified diff format". That is, removed lines are prefaced with - and added lines are prefaced with a +. svn diff also prints filename and offset information useful to the patch program, so you can generate patches by redirecting the diff output to a file:

svn diff > patchfile

cd DART/obs_def
svn diff DEFAULT_obs_def_mod.F90 > patchfile
scp -p patchfile my.other.machine.edu:DART/obs_def
log on to other machine
cd DART/obs_def
patch -p0 < patchfile

If you want diff output in a different format, specify an external diff program using --diff-cmd and pass any flags using the --extensions switch. [footnote pp. 31 of svn-book.pdf] If you use the default, your modifications are prefixed with a '+', the 'other' lines are prefixed with a '-'. Be aware that 'other' could be HEAD (svn diff -r HEAD ...) and could be NEWER than your modifications!

Example: comparing your modifications to the same version you started with.
In this example, there are a couple lines that are just to get you oriented, they start with neither a '-' nor a '+'. The lines starting with '+' are your modifications.

0[119] cr0122en:/<4>SVN/DART/obs_def > svn diff DEFAULT_obs_def_mod.F90
Index: DEFAULT_obs_def_mod.F90
===================================================================
--- DEFAULT_obs_def_mod.F90     (revision 2884)
+++ DEFAULT_obs_def_mod.F90     (working copy)
@@ -30,8 +30,16 @@
                              KIND_TEMPERATURE, KIND_SPECIFIC_HUMIDITY, KIND_PRESSURE, &
                              KIND_VERTICAL_VELOCITY, KIND_RAINWATER_MIXING_RATIO, &
                              KIND_DEW_POINT_TEMPERATURE, KIND_DENSITY, KIND_VELOCITY, &
-                             KIND_1D_INTEGRAL, KIND_RADAR_REFLECTIVITY, &
-                             KIND_POTENTIAL_TEMPERATURE
+                             KIND_RADAR_REFLECTIVITY, KIND_1D_INTEGRAL, &
+                             KIND_GRAUPEL_MIXING_RATIO, KIND_SNOW_MIXING_RATIO, &
+                             KIND_GPSRO, KIND_CLOUD_LIQUID_WATER, KIND_CLOUD_ICE, &
+                             KIND_CONDENSATIONAL_HEATING, KIND_VAPOR_MIXING_RATIO, &
+                             KIND_ICE_NUMBER_CONCENTRATION, KIND_GEOPOTENTIAL_HEIGHT, &
+                             KIND_POTENTIAL_TEMPERATURE, KIND_SOIL_MOISTURE, &
+                             KIND_GRAV_WAVE_DRAG_EFFIC, KIND_GRAV_WAVE_STRESS_FRACTION, &
+                             KIND_TRACER_SOURCE, KIND_TRACER_CONCENTRATION, &
+                             KIND_VORTEX_LON, KIND_VORTEX_LAT, &
+

Another very useful variation is the ability to see what is different from one release or branch to another. The next example will show precisely which files are different - in the repository. Your working copies (if any) are immaterial.

svn diff --summarize https://proxy.subversion.ucar.edu/DAReS/DART/releases/Kodiak \
                     https://proxy.subversion.ucar.edu/DAReS/DART/trunk

svn update

bring your working copy "up-to-date" with the repository. NOTE: if you have local modifications to the file, they are preserved (if possible) during the update. As long as the modifications do not conflict with changes in the repository, your changes will last through the update.

Example:

0[508] dart:~/SVN/DART > svn update
U  location/threed_sphere/location_mod.f90
U  models/lorenz_96/model_mod.f90
U  models/wrf/work/runme_filter
U  models/wrf/shell_scripts/advance_model.csh
U  ensemble_manager/ensemble_manager_mod.html
U  filter/filter.f90
A  filter/filter.dopplerfold.f90
U  obs_kind/DEFAULT_obs_kind_mod.F90
A  mkmf/mkmf.template.intel.osx
U  utilities/utilities_mod.f90
Updated to revision 2681.
0[509] dart:~/SVN/DART >

If there is a conflict - fear not. Subversion makes copies of

1. the file as it was before the update,
2. the revision of the file you had modified,
3. the HEAD revision of the file, and
4. the conflicted union of the modifications and the HEAD.

if you want to get version 4567 of a deleted file back, you can either:

svn cat https://blah.blah/bob.f90@4567 > oldbob.f90

or

svn update https://blah.blah/bob.f90@4567

svn revert

Example:

svn resolved

Unlike CVS, subversion 'remembers' that a file is in conflict and will not allow a file that is in conflict to be committed to the repository. You must first clear the 'conflicted' status with resolved.

Example:

0[675] dart:~/DART/shell_scripts > svn status
?      bob.r2657
?      bob.r2658
?      bob.mine
C      bob
0[676] dart:~/DART/shell_scripts > (a miracle happens)
0[677] dart:~/DART/shell_scripts > svn commit -m "now slices bread"
svn: Commit failed (details follow):
svn: Aborting commit: '/fs/image/home/thoar/SVN/DART/shell_scripts/bob' remains in conflict
doh!
1[678] dart:~/DART/shell_scripts > svn resolved bob
Resolved conflicted state of 'bob'
0[679] dart:~/DART/shell_scripts > svn commit -m "now slices bread"
Sending        shell_scripts/bob
Transmitting file data .
Committed revision 2659.
0[680] dart:~/DART/shell_scripts >

svn switch

Here's the command for changing from one branch to another. The files will be updated to match the new branch, while leaving the local modifications alone if possible.

Example: Lets' say you've been updating from the trunk (the development branch) and you want to move to the Kodiak release without losing any local modifications you've made to your project - which I'll call ~/SVN/DART

0[577] dart:~/SVN/DART > svn switch https://proxy.subversion.ucar.edu/DAReS/DART/releases/Kodiak

Here's the command for changing the server address of the svn tree when the content isn't changing, just the urls:

Example:

0[577] dart:~/SVN/DART > svn switch --relocate http://subversion.ucar.edu/DAReS/DART/trunk https://subversion.ucar.edu/DAReS/DART/trunk .

If you ever see an S in the 5th column of the 'svn status' command, that means that directory is switched relative to the rest of the dirs. I don't recommend doing this -- seems like it just leads to massive confusion -- but i just ran into one last week where i'd been experimenting and had apparently done this. would have caused a lot of confusion about why it wasn't updating with the rest of the trunk.

For Those Who Can Write to the repository

 
[tarpon:~] thoar% svn list http://subversion.ucar.edu/DAReS/DART
[tarpon:~] thoar% svn checkout --revision 2188 http://subversion.ucar.edu/DAReS/DART/trunk DART_post_iceland
[tarpon:~] thoar% svn checkout --revision 2884 http://subversion.ucar.edu/DAReS/DART/trunk DART_Jamaica

svn add

Example:

svn rm

This one is nice because you can use wildcards to remove sets of files - OR DIRECTORIES! Whooohooo! No more 'pruning empty directories'.    excellent ...

Example:

0[578] dart:~/SVN/DART/shell_scripts > svn rm bob
D         bob
0[579] dart:~/SVN/DART/shell_scripts > 

svn delete

Example:

svn rename (aka 'move')

Example: (where the target file already exists) Note the log entries move with the file! Whooohoooo!!!!

0[528] dart:~/<2>models/PBL_1d/src > svn rename driver.F driver.F90
svn: File 'driver.F90' already exists
1[529] dart:~/<2>models/PBL_1d/src > rm driver.F90 
0[530] dart:~/<2>models/PBL_1d/src > svn rename driver.F driver.F90 
A         driver.F90
D         driver.F
0[531] dart:~/<2>models/PBL_1d/src >  svn commit -m "renamed driver.F to 
driver.F90 because it really uses the f90 syntax and the .F extension usually 
causes compilers to assume f77 syntax" driver.F90 
Adding         driver.F90

Committed revision 2715.
0[532] dart:~/<2>models/PBL_1d/src >  svn log driver.F90
------------------------------------------------------------------------
r2715 | thoar | 2007-03-26 13:40:16 -0600 (Mon, 26 Mar 2007) | 1 line

renamed driver.F to driver.F90 because it really uses the f90 syntax and the .F
extension usually causes compilers to assume f77 syntax
------------------------------------------------------------------------
r2713 | thoar | 2007-03-25 22:09:04 -0600 (Sun, 25 Mar 2007) | 3 lines

New copyright tag (up-to-date for 2007)
New URL keyword instead of (unsupported) 'Source'.

...

svn copy

Example:

svn commit

Example:

svn propset

Example:

0[577] dart:~/SVN/DART/shell_scripts > svn propset svn:keywords "Date Revision Author HeadURL Id" bob
0[578] dart:~/SVN/DART/shell_scripts > svn commit -m "added properties" bob 

svn propset svn:mime-type text/html `find . -name "*.html" -print | grep -v .svn`
svn propset svn:eol-style native *.m
svn propset svn:executable runme_filter

Note that the quotes around the propset string are OK ... but if you do a propget and get quotes, they're wrong. Your .subversion/config file should NOT have quotes in it.

svn proplist

Example:

0[577] dart:~/DART/models/POP > svn proplist -v test_dipole_interp.f90

svn propdel

Example:

0[577] dart:~/DART/models/POP > svn propdel svn:executable test_dipole_interp.f90

restoring/recovering a file/directory

Example 1: (assumes you can find the exact revision you like)

svn log --verbose | & tee my.log
(grub through log to find version number you want ...)
svn copy --revision 2527 http://subversion.ucar.edu/DAReS/DART/trunk/system_simulation ./system_simulation

or

svn cat https://blah.blah/bob.f90@2527 > bob_2527.f90

modifying a log message

I found an incantation which is supposed to let you edit svn log messages. Since log messages aren't versioned, you have to be careful. But if there are obnoxious typos or outright errors, it is fixable. I haven't quite zero'd in on how to fix multiline messages (it doesn't invoke vi, it's a command line argument) but at least it's possible.

Here's an example command - the key is the --revprop argument at the end. The book says you can use propset instead of propget to update, but I haven't tried it yet.

Example 1: (assumes you can find the exact revision you like)

svn propget svn:log -r HEAD model_mod.f90 --revprop