graphein: Revision Control (Subversion)

1. Revision Control (Subversion)

1.1. General Notes

A graphein-based document system should be kept under some kind of revision control system. I use Subversion, but as graphein is not closely tied to any revision control system, any system could be used. I'll only offer here a few miscellaneous notes.

I found the book Version Control with Subversion by Ben Collins-Sussman, Brian W. Fitzpatrick, and C. Michael Pilato (at http://svnbook.red-bean.com/) to be quite useful.

graphein doesn't use the Subversion "keyword" mechanism (Id, Revision, Date, etc.) It allows equivalent information to be kept for each source file in its teiHeader.

1.2. Status and List Commands

The "svn status" command gives the status of all files from the current working directory down, including those not in Subversion control. To find the status of only svn-controlled files, filter its output to exclude the "?" character:

 
svn status | grep -v "\?" 

The "svn list" command can in general list the repository contents at any revision level. I can't find any reference in the SVN documentation or elsewhere to the default revision level if it is not specified, but it seems to be the revision level of the checked-out tree at the time you checked it out. I find this to be quite confusing, as this is by no means the same as the current contents of the repository! To force "svn list" to use the current revision level, use the "-r HEAD" parameter. Thus, to list the repository's contents at the current revision level (and at the same point in the tree as you are in your checked-out copy, which is the default behavior), verbosely (-v), do:

 
svn list -v -r HEAD 

(The default behavior for revision levels seems equivalent to specifying, instead, "-r BASE".)

1.3. Cribsheet

1.3.1. Status/Listing Cribs

svn status | grep -v "\?"

svn list -v -r HEAD

svn status | grep -v "find-location" | grep -v "makefile"

1.3.2. Add and New Subdirectory Cribs

svn add FILENAME

After creating a new graphein subdirectory (with make-subdirectory.sh), "svn add" it immediately, or at least before doing any make/build in it (that picks up all of the real, initial contents, but doesn't pick up any additional temporary contents from the make/build). Afterwards, "svn add" individual source files as (after) they're created.

DON'T FORGET TO svn add NEW FILES, or they'll never make it to the repository and will disappear when you discard the current checkout.

1.3.3. Commit Crib

svn commit -m "LOGMESSAGE"

This gets around a bug I encountered where an interactive commit message caused the command to fail.

1.3.4. Checkout Crib

The command for an project subtree checkout is (assuming a repository on the local system in /data0/scriptorium/svn-scriptorium", a project named "circuitousroot", and a checkout also of the same name, "circuitousroot"):

svn checkout file:///data0/scriptorium/svn-scriptorium/circuitousroot/trunk circuitousroot

1.3.5. Moving the Repository Crib

If you've moved the repository while a checked-out version has uncommitted updates that you wish to commit (e.g., after the disk crashed again), do (for example):

svn switch --relocate file:///data0/svn-scriptorium/circuitousroot/trunk file:///data0/scriptorium/svn-scriptorium/circuitousroot/trunk