From owner-freebsd-doc  Thu Jul 31 08:02:13 1997
Return-Path: <owner-freebsd-doc>
Received: (from root@localhost)
          by hub.freebsd.org (8.8.5/8.8.5) id IAA13817
          for doc-outgoing; Thu, 31 Jul 1997 08:02:13 -0700 (PDT)
Received: from palrel3.hp.com (palrel3.hp.com [156.153.255.219])
          by hub.freebsd.org (8.8.5/8.8.5) with ESMTP id IAA13811;
          Thu, 31 Jul 1997 08:02:11 -0700 (PDT)
Received: from postbox.india.hp.com (postbox.india.hp.com [15.10.45.1])
	by palrel3.hp.com (8.8.5/8.8.5) with ESMTP id IAA09373;
	Thu, 31 Jul 1997 08:02:02 -0700 (PDT)
Message-Id: <199707311502.IAA09373@palrel3.hp.com>
Received: from localhost by postbox.india.hp.com with ESMTP
	(1.39.111.2/16.2) id AA021321213; Thu, 31 Jul 1997 20:30:13 +0530
To: phk@freebsd.org, freebsd-doc@freebsd.org
Subject: Update to CTM tutorial
Date: Thu, 31 Jul 1997 20:30:13 +0530
From: A Joseph Koshy <koshy@india.hp.com>
Sender: owner-freebsd-doc@freebsd.org
X-Loop: FreeBSD.org
Precedence: bulk


Hi,

I found the CTM tutorial in the Handbook a bit dated so I've done the 
needful and added a new section to it while at the job.  Could someone 
please commit this?

Koshy
<koshy@india.hp.com>				My Personal Opinions Only.

Index: ctm.sgml
===================================================================
RCS file: /usr/cvs/doc/handbook/ctm.sgml,v
retrieving revision 1.19
diff -u -r1.19 ctm.sgml
--- ctm.sgml	1997/06/02 16:42:21	1.19
+++ ctm.sgml	1997/07/31 15:32:59
@@ -16,7 +16,7 @@
 
 <sect1><heading>CTM<label id="ctm"></heading>
 
-<p><em>Contributed by &a.phk;.  Updated 16-Mar-1995.</em>
+<p><em>Contributed by &a.phk;.  Updated 31-July-1997.</em>
 
         <tt/CTM/ is a method for keeping a remote directory tree in sync with a
         central one.  It has been developed for usage with FreeBSD's source
@@ -108,11 +108,13 @@
         all deltas with higher numbers following it.
 
     <sect2><heading>Using <tt/CTM/ in your daily life</heading>
-      <p>To apply the deltas, simply say
-        <verb>
-          cd /where/ever/you/want/the/stuff
-          ctm -v -v /where/you/store/your/deltas/src-cur.*
-        </verb>
+      <p>
+        To apply the deltas, simply say:
+        <tscreen><verb>
+cd /where/ever/you/want/the/stuff
+ctm -v -v /where/you/store/your/deltas/src-cur.*
+        </verb></tscreen>
+      <p>
         <tt/CTM/ understands deltas which have been put through <tt/gzip/,
         so you do not need to gunzip them first, this saves disk space.
 
@@ -122,8 +124,8 @@
 	merely verify the integrity of the delta and see if it would apply
         cleanly to your current tree.
 
-        There are other options to <tt/CTM/ as well, look in the sources
-        for more details.
+        There are other options to <tt/CTM/ as well, see the manual pages
+        or look in the sources for more information.
 
         I would also be very happy if somebody could help with the ``user
         interface'' portions, as I have realized that I cannot make up my
@@ -137,24 +139,69 @@
         Even if you only have floppy disks, consider using <tt/fdwrite/ to
         make a copy.
 
+    <sect2><heading>Keeping your local changes</heading>
+     <p>
+      As a developer one would like to experiment with and change
+      files in the source tree.  CTM supports local modifications in a
+      limited way: before checking for the presence of a file
+      <tt>foo</tt>, it first looks for <tt>foo.ctm</tt>.  If this
+      file exists, CTM will operate on it instead of <tt>foo</tt>.
+     <p>
+      This behaviour gives us a simple way to maintain local changes:
+      simply copy the files you plan to modify to the corresponding
+      file names with a <tt>.ctm</tt> suffix.  Then you can freely hack 
+      the code, while CTM keeps the <tt>.ctm</tt> file upto-date.
+    
+    <sect2><heading>Other interesting CTM options</heading>
+     <sect3><heading>Finding out exactly what would be touched by an update</heading>
+      <p>
+       You can determine the list of changes that CTM will make on your
+       source repository using the ``<tt>-l</tt>'' option to CTM.
+      <p>
+       This is useful if you would like to keep logs of the changes, 
+       pre- or post- process the modified files in any manner, or just 
+       are feeling a tad paranoid :-).
+
+     <sect3><heading>Making backups before updating</heading>
+      <p>
+       Sometimes you may want to backup all the files that would be changed
+       by a CTM update.
+      <p>
+       Specifying the ``<tt>-B backup-file</tt>'' option causes
+       CTM to backup all files that would be touched by a given CTM
+       delta to <tt>backup-file</tt>.
 
-    <sect2><heading>Future plans for <tt/CTM/</heading>
+     <sect3><heading>Restricting the files touched by an update</heading> 
+      <p>
+       Sometimes you would be interested in restricting the scope of a
+       given CTM update, or may be interested in extracting just a few
+       files from a sequence of deltas.
+      <p>
+       You can control the list of files that CTM would operate on by
+       specifying filtering regular expressions using the
+       ``<tt>-e</tt>'' and ``<tt>-x</tt>'' options.
+      <p>
+       For example, to extract an upto-date copy of 
+       <tt>lib/libc/Makefile</tt> from your collection of saved CTM deltas,
+       run the commands:
+      <tscreen><verb>
+cd /where/ever/you/want/to/extract/it/
+ctm -e '^lib/libc/Makefile' ~ctm/src-cur.*
+      </verb></tscreen>
+      <p>
+       For every file specified in a CTM delta, the ``<tt>-e</tt>'' and
+       ``<tt>-x</tt>'' options are applied in the order given on the
+       command line.  The file is processed by CTM only if it is
+       marked as eligible after all the ``<tt>-e</tt>'' and
+       ``<tt>-x</tt>'' options are applied to it.
+
+       <sect2><heading>Future plans for <tt/CTM/</heading>
       <p>
         Tons of them:
         <itemize>
           <item>
-            Make local modifications to the tree possible.  One way to do
-            it could be this:<p> When <tt/CTM/ wants to edit the file
-            ``<tt>foo/bar.c</tt>'', it would first check for the existence
-            of <tt>foo/bar.c&num;CTM</tt> If this file exists, the delta is
-            applied to it instead.  This way the <tt>foo/bar.c</tt> file
-            can be edited to suit local needs.
-          <item>
-            Make a ``restore file(s)'' option to <tt/CTM/, something like:
-            <verb>
-      ctm -r src/sys/i386/wd.c /here/are/my/deltas/src-cur.*
-            </verb>
-            would restore <tt/wd.c/ to the current status from the files.
+            Use some kind of authentication into the CTM system, so as to
+            allow detection of spoofed CTM updates.
           <item>
             Clean up the options to <tt/CTM/, they became confusing and
             counter intuitive.