From: Eric S. Raymond <esr@thyrsus.com>
Date: Sun, 9 Nov 2014 12:09:25 +0000 (-0500)
Subject: Add implementation notes.
X-Git-Tag: 0.3~14
X-Git-Url: http://thyrsus.com/gitweb/?a=commitdiff_plain;h=d428cbcc8f93427103f5c09011f5c099e7830c67;p=src.git

Add implementation notes.
---

diff --git a/src b/src
index cadb222..8713c83 100755
--- a/src
+++ b/src
@@ -2,6 +2,25 @@
 #
 # src - simple revision control.
 #
+# Things to know before hacking this:
+#
+# All the code outside the RCS class is intended to be generic to any
+# file-oriented VCS. Try to keep it that way; in particular, support
+# for SCCS is an eventual goal.
+#
+# SRC and RCS have different goals in managing locks. RCS wants to keep
+# the workfile read-only except when it's explicitly checked out, SRC wants to
+# leave it writeable all the time.  Thus, the checkin sequence is "release
+# lock; check in; assert lock". If this seems confusing, it's because in
+# RCS rerminology, locked is writeable and unlocked is read-only.
+#
+# The "src status" command needs to be fast so that Emacs VC won't be sluggish.
+# It's written to only have to access the inodes of each master and workfile,
+# not the files themselves.  The central trick is the use of utimes(2) to
+# set the master's modification time just after the workfile is checked out;
+# thus, to distinguish between U and M status all we need to do is compare
+# modtimes.
+#
 import sys, os, subprocess, time, calendar, stat, glob
 
 version=0.2
@@ -820,7 +839,7 @@ class RCS:
         # log display.  This gives us plenty of slack to cope with
         # minor format differences.
         #
-        # The motivation here is to make "src status" faster by avoid
+        # The motivation here is to make "src status" faster by avoiding
         # the need for an entire log parse when checking for "A"
         # status.
         return os.path.getsize(self.master(arg)) > 105