$OpenBSD: patch-ctm_ctm_ctm_1,v 1.3 2010/04/03 19:39:50 naddy Exp $
--- ctm/ctm/ctm.1.orig	Wed May  1 01:01:43 1996
+++ ctm/ctm/ctm.1	Sat Apr  3 21:14:18 2010
@@ -1,5 +1,5 @@
 .\"----------------------------------------------------------------------------
-.\""THE BEER-WARE LICENSE" (Revision 42): 
+.\""THE BEER-WARE LICENSE" (Revision 42):
 .\"<joerg@freebsd.org> wrote this file.  As long as you retain this notice you
 .\"can do whatever you want with this stuff. If we meet some day, and you think
 .\"this stuff is worth it, you can buy me a beer in return.       Joerg Wunsch
@@ -20,157 +20,267 @@
 .Nd source code mirror program
 .Sh SYNOPSIS
 .Nm ctm
-.Op Fl cFpPquv
+.Op Fl cFklquv
 .Op Fl b Ar basedir
+.Op Fl B Ar backup-file
+.Op Fl e Ar include-regex
+.Op Fl t Ar tar-command
 .Op Fl T Ar tmpdir
 .Op Fl V Ar level
-.Ar file Op ...
+.Op Fl x Ar exclude-regex
+.Ar
 .Sh DESCRIPTION
-.Nm Ctm
+.Nm
 was originally
 .Dq Cvs Through eMail ,
 but now instead it seems more fitting to call it
 .Dq Current Through eMail .
-
-.Nm Ctm
+.Pp
+.Nm
 is now meant to be the definitive way to make and apply a delta between
 two versions of a directory tree.
-
-There are two parts to this, making the delta and applying it.  These are two
+.Pp
+There are two parts to this, making the delta and applying it.
+These are two
 entirely different things.
-
 .Ss Usage
-
 To apply a CTM delta, you pass it to the
-.Nm ctm
-command.  You can pass a CTM delta on stdin, or you can give the
-filename as an argument.  If you do the latter, you make life a lot
-easier for your self, since the program can accept gzip'ed files and
-since it will not have to make a temporary copy of your file.  You can
-specify multiple deltas at one time, they will be proccessed one at a
-time.  Deltas that are already applied will be ignored.
-
+.Nm
+command.
+You can pass a CTM delta on stdin, or you can give the
+filename as an argument.
+If you do the latter, you make life a lot
+easier for yourself, since the program can accept gzip'ed files and
+since it will not have to make a temporary copy of your file.
+You can
+specify multiple deltas at one time, they will be processed one at a
+time.
+Deltas that are already applied will be ignored.
+.Pp
 The
-.Nm ctm
-command runs in a number of passes.  It will process the entire
+.Nm
+command runs in a number of passes.
+It will process the entire
 input file in each pass, before commencing with the next pass.
-
-Before working one a file
+.Pp
+Before working on a file
 .Ar name
-.Nm ctm
+.Nm
 first checks for the existence of the file
 .Ar name.ctm .
 If this file exists,
-.Nm ctm
+.Nm
 works on it instead.
-
-Pass 1 will validate that the input file is OK.  The syntax, the data
-and the global MD5 checksum will be checked.  If any of these fail,
-.Nm ctm
-will never be able to do anything with the file, so it will simply
-reject it.
-
+.Pp
+Pass 1 will verify that the input file is OK.
+The syntax, the data
+and the global MD5 checksum will be checked.
+If any of these fail,
+.Nm
+will simply reject the input file.
+.Pp
 Pass 2 will validate that the directory tree is in the state expected by
-the CTM delta.  This is done by looking for files and directories which
-should/should not exists and by checking the MD5 checksums of files.  
-
-Pass 3 will actually apply the delta.
-
-.Nm Ctm
-will extract the file hierarchy below its working directory.  Absolute
-filenames or filenames containing references through
-.Sq \&.
+the CTM delta.
+This is done by looking for files and directories which
+should/should not exist and by checking the MD5 checksums of files.
+.Pp
+If a
+.Ar backup-file
+had been specified using the 
+.Fl B
+option, all files that would be modified by this 
+.Nm
+invocation are backed up
+to this file using the archiver command specified by the 
+.Fl t
+option.  The default archiver command is
+.Nm "tar -rf %s -T -" .
+.Pp
+Pass 3 will actually apply the delta. 
+.Pp
+The list of files that would be modified by
+.Nm
+is subject to filtering regular expressions specified
+using the
+.Fl e
 and
-.Sq \&.\&.
+.Fl x
+options.
+The
+.Fl e
+and 
+.Fl x
+options are applied in order of appearance on the command line.
+The last
+filter that matched a given file name determines whether the file would be 
+operated on or left alone by
+.Nm ctm .
+.Pp
+.Nm
+will extract the file hierarchy below its working directory.
+Absolute
+filenames or filenames containing references through
+.Dq \&.
+or
+.Dq \&.\&.
 are explicitly prohibited as a security measure.
-
+.Pp
 .Ss Options
-
-.Bl -tag -width indent -compact
-
+.Bl -tag -width indent
 .It Fl b Ar basedir
 Prepend the path
 .Ar basedir
-on every filename.
-
+to every filename.
+.It Fl B Ar backup-file
+Backup all files that would be modified by this CTM run to
+.Ar backup-file .
+If any filters are specified using the
+.Fl e
+and
+.Fl x
+options, then the final set of files backed up are those that would be
+modified by CTM after the filters are applied.
 .It Fl c
 Check it out, don't do anything.
-
+.It Fl e Ar regular_expression
+Match each name in the CTM file against
+.Ar regular_expression ,
+and if it matches process the file, otherwise leave it alone.
+There may be
+any number of these options.
+Use of this option disables the
+.Pa .ctm_status
+sequence number checks.
+For example, the expression 
+.Ic ^usr.sbin/ctm 
+for example, will select the
+.Pa usr.sbin/ctm
+source directory and all pathnames under it. 
+.Pp
+Pathnames can be disabled from being considered by CTM using the 
+.Fl x
+option.
 .It Fl F
 Force.
-
-.It Fl p
-Less paranoid.
-
-.It Fl P
-Paranoid.
-
+.It Fl k
+Keep files and directories and don't remove them even if the CTM file
+specifies they are to be removed.
+If the
+.Fl B
+option is specified, these files and directories will not be backed up.
+.It Fl l
+List files that would be modified by this invocation of CTM and the
+actions that would be performed on them.
+Use of the
+.Fl l
+option disables the
+.Pa .ctm_status
+checks and integrity checks on the source tree being operated on.
+The
+.Fl l
+option can be combined with the 
+.Fl e
+and
+.Fl x
+options to determine which files would be modified by the given set of
+command line options.
 .It Fl q
 Tell us less.
-
+.It Fl t Ar tar-command
+Use
+.Ar tar-command
+instead of the default archiver
+.Nm tar .
+This option takes effect only if a backup file had been specified using the
+.Fl B
+option.
+A %s in the tar command will be replaced by the name of the backup 
+file.
 .It Fl T Ar tmpdir
 Put temporary files under
 .Ar tmpdir .
-
 .It Fl u
-Set modification time of created and modified files to the CTM delta
+Set the modification time of created and modified files to the CTM delta
 creation time.
-
 .It Fl v
 Tell us more.
-
 .It Fl V Ar level
 Tell us more.
-.Ar Level
+.Ar level
 is the level of verbosity.
-
+.It Fl x Ar regular_expression
+Match each name in the CTM file against
+.Ar regular_expression
+and if it matches, leave the file alone.
+There may be any number of these
+options.  Use of this option disables the
+.Pa .ctm_status
+sequence number checks.   
+.Pp
+Pathnames can be selected for CTM's consideration using the
+.Fl e
+option.
 .El
-
-
+.Sh ENVIRONMENT
+.Ev TMPDIR,
+if set to a pathname, will cause
+.Nm
+to use that pathname
+as the location of temporary file.
+See
+.Xr tempnam 3
+for more details on this.
+The same effect may be achieved with the
+.Fl T
+flag.
 .Sh FILES
-
 .Pa .ctm_status
-contains the sequence number of the last CTM delta applied.  Changing
+contains the sequence number of the last CTM delta applied.
+Changing
 or removing this file will greatly confuse
 .Nm ctm .
-
+Using the
+.Fl e
+and
+.Fl x
+options can update a partial subset of the source tree and causes sources
+to be in an inconsistent state.
+It is assumed that you know what you are
+doing when you use these options.
 .Sh EXAMPLES
-
 .Bd -literal
-
 cd ~cvs
 /usr/sbin/ctm ~ctm/cvs-*
-
 .Ed
-
+.Pp
+To extract and patch all sources under `lib'
+.Bd -literal
+cd ~/lib-srcs
+/usr/sbin/ctm -e '^lib' ~ctm/src-cur*
+.Ed
 .Sh DIAGNOSTICS
-
-Numerous messages, hopefully self-explaining.  The
+Numerous messages, hopefully self-explanatory.
+The
 .Dq noise level
 can be adjusted with the
-.Fl q
-and
+.Fl q ,
 .Fl v
+and
+.Fl V
 options.
-
 .Sh SEE ALSO
-
+.Xr ctm_rmail 1 ,
 .Xr ctm 5
-
 .Sh HISTORY
-
-Initial trials ran during the FreeBSD 1.1.5, and many bugs and 
+Initial trials were run during the work on FreeBSD 1.1.5, and many bugs and
 methods were hashed out.
-
 The
-.Nm ctm
+.Nm
 command appeared in FreeBSD 2.1.
-
 .Sh AUTHORS
-
 The CTM system has been designed and implemented by
 Poul-Henning Kamp
 .Aq phk@FreeBSD.org .
-
-Joerg Wunsch wrote this man-page.
-.Aq joerg@FreeBSD.org .
+Joerg Wunsch
+.Aq joerg@FreeBSD.org
+wrote this man page.
