KAGRA VIS Operations Manual

Subversion (a.k.a. svn) is a version control system based on the Apache web server. LIGO uses it for keeping track of all real-time models, screens, etc (everything in userapps among other things), and KAGRA is set up to use it but needs everyone to be more diligent about using it.

The full documentation is available at http://svnbook.red-bean.com. Highlights follow.

Subversion is structured in terms of a server that hosts an svn repository with the master copy of some code or data (e.g., for KAGRA, https://granite.phys.s.u-tokyo.ac.jp/svn/KAGRA/trunk/userapps/trunk), and one or more "working copies" of some or all of the repository that have been "checked out" on other computers (e.g., opt/rtcds/userapps/trunk). After one or more files in a working copy have been edited, they can be "committed" back to the repository. (There is provision for conflict resolution if different users attempt to commit incompatible changes from different working copies, but this should rarely be relevant because there is only one detector, and the control room machines see the same working copy, which has been checked out onto a network drive.)

Commands of interest

Almost all the following commands act on the entire directory by default but can be given a list of files (or wildcards) to narrow the action.

• svn info checks whether the current directory is a working copy and returns various info such as the URL of the server. (Each working copy directory has an invisible .svn subdirectory with various data including an unmodified copy of all the files.)

• svn status (or svn st) returns a listing of any files in the current directory and their status:

  •   (space) = the file is unmodified relative to the last update.

  • M = modified - the user has modified this file and svn has noticed the change.

  • ? = not under version control - the file has been created locally, but svn has not been told about it.

  • A = added - the user has told svn about this file with an svn add command, but has not yet committed it.

  • D = deleted - the user has told svn to delete this file, and svn has removed the local copy, but has not committed the change.

  • ! = missing - the user deleted the file without informing svn.

  • C = conflict - the local file is modified (as for M) and svn has noticed that the repository has a different modification.

  • I = ignore - this is a local file that svn has been told to ignore because it's not helpful to upload it to the repository.

  • etc - see manual.

• svn update (or svn up) attempts to download the most recent version of each file from the repository. However it will not overwrite local modifications.

• svn commit -m "comment" (or svn ci -m "comment") attempts to upload local changes as a new version to the repository. The comment flag is mandatory. Do try to add a useful comment describing changes you have made, but if there really isn't anything useful to say, use an empty string.

• svn add adds new files to the version-controlled set (ignoring any already version-controlled ones). The added files get uploaded at the next svn commit.

• svn delete deletes files. The local copy is deleted immediately and the copy on the repository is deleted at the next svn commit.

• svn revert deletes locally modified files and restores the version from the last svn update (not necessarily the latest version on the server).

• svn move oldname newname (or svn mv ...) renames a file locally, then does svn delete oldname and svn add newname.

Good habits

• After a session of editing anything in userapps, do an svn ci on it with a helpful comment.

• After creating a new file in userapps, do an svn add and an svn ci.

• From time to time, do svn st in each directory in userapps that you have some responsibility for. If there are any new or modified files that you forgot to commit, fix them, and if there are any that someone else forgot about, do it for them or nag them.

• If you come across any files not in userapps or another version-controlled area but are logically part of the configuration of the detector (e.g., the safe.snap files in directories like /opt/rtcds/kamioka/k1/target/k1visbst/k1visbstepics/) consider making them symbolic links to files within userapps.