From 694a8742e7325a413635000b2eb9dadfe4a6fbae Mon Sep 17 00:00:00 2001 From: joerg Date: Sat, 25 Mar 1995 18:14:26 +0000 Subject: [PATCH] Added a man page for the ctm(1) command, as well as a format description for the CTM deltas. Largely based on Poul-Henning's README, and the source code. --- usr.sbin/ctm/ctm/Makefile | 5 +- usr.sbin/ctm/ctm/ctm.1 | 146 +++++++++++++++++++++++++++ usr.sbin/ctm/ctm/ctm.5 | 206 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 355 insertions(+), 2 deletions(-) create mode 100644 usr.sbin/ctm/ctm/ctm.1 create mode 100644 usr.sbin/ctm/ctm/ctm.5 diff --git a/usr.sbin/ctm/ctm/Makefile b/usr.sbin/ctm/ctm/Makefile index 3d7745336976..eac26208f701 100644 --- a/usr.sbin/ctm/ctm/Makefile +++ b/usr.sbin/ctm/ctm/Makefile @@ -6,7 +6,7 @@ # this stuff is worth it, you can buy me a beer in return. Poul-Henning Kamp # ---------------------------------------------------------------------------- # -# $Id: Makefile,v 1.6 1994/10/24 20:09:18 phk Exp $ +# $Id: Makefile,v 1.7 1995/03/04 20:36:44 phk Exp $ # PROG= ctm @@ -15,7 +15,8 @@ SRCS= ctm.c ctm_input.c ctm_pass1.c ctm_pass2.c ctm_pass3.c \ ctm_syntax.c ctm_ed.c LDADD+= -lmd DPADD+= ${LIBMD} -NOMAN= 1 +MAN1= ctm.1 +MAN5= ctm.5 CFLAGS+= -Wall -g .if exists(${.CURDIR}/../../Makefile.inc) diff --git a/usr.sbin/ctm/ctm/ctm.1 b/usr.sbin/ctm/ctm/ctm.1 new file mode 100644 index 000000000000..9deeb85b1701 --- /dev/null +++ b/usr.sbin/ctm/ctm/ctm.1 @@ -0,0 +1,146 @@ +.\"---------------------------------------------------------------------------- +.\""THE BEER-WARE LICENSE" (Revision 42): +.\" 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. Poul-Henning Kamp +.\"---------------------------------------------------------------------------- +.\" +.\" This manual page is partially obtained from Poul-Hennings CTM README +.\" file. +.\" +.\" CTM and ctm(1) by +.\" +.\" $Id$ +.\" +.Dd Mar 25, 1995 +.Os +.Dt CTM 1 +.Sh NAME +.Nm ctm +.Nd source code mirror program +.Sh SYNOPSIS +.Nm ctm +.Op Fl cFpPqv +.Op Fl T Ar tmpdir +.Ar file Op ... +.Sh DESCRIPTION +.Nm Ctm +was originally +.Dq Cvs Through eMail , +but has since changed scope to be much more general. + +.Nm Ctm +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 +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. + +The +.Nm ctm +command runs in a number of passes. It will process the entire +input file in each pass, before commencing with the next pass. + +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. + +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 \&. +and +.Sq \&.\&. +are explicitly prohibited as a security measure. + +.Ss Options + +.Bl -tag -width indent -compact + +.It Fl c +Check it out, don't do anything. + +.It Fl F +Force. + +.It Fl p +Less paranoid. + +.It Fl P +Paranoid. + +.It Fl q +Tell us less. + +.It Fl T Ar tmpdir +Put temporary files under +.Ar tmpdir . + +.It Fl v +Tell us more. + +.El + + +.Sh FILES + +.Pa .ctm_status +contains the sequence number of the last CTM delta applied. Changing +or removing this file will greatly confuse +.Nm ctm . + +.Sh EXAMPLES + +.Bd -literal + +cd ~cvs +/usr/sbin/ctm ~ctm/cvs-* + +.Ed + +.Sh DIAGNOSTICS + +Numerous messages, hopefully self-explaining. The +.Dq noise level +can be adjusted with the +.Fl q +and +.Fl v +options. + +.Sh SEE ALSO + +.Xr ctm 5 +.Pq yet to be written . + +.Sh HISTORY + +The +.Nm ctm +command appeared in FreeBSD 2.1. + +.Sh AUTHORS + +The CTM system has been designed and implemented by +Poul-Henning Kamp +.Aq phk@FreeBSD.org . + diff --git a/usr.sbin/ctm/ctm/ctm.5 b/usr.sbin/ctm/ctm/ctm.5 new file mode 100644 index 000000000000..a3bd0e0d3615 --- /dev/null +++ b/usr.sbin/ctm/ctm/ctm.5 @@ -0,0 +1,206 @@ +.\"---------------------------------------------------------------------------- +.\""THE BEER-WARE LICENSE" (Revision 42): +.\" 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. Poul-Henning Kamp +.\"---------------------------------------------------------------------------- +.\" +.\" This manual page is partially obtained from Poul-Hennings CTM README +.\" file. +.\" +.\" CTM and ctm(1) by +.\" +.\" $Id$ +.\" +.Dd March 25, 1995 +.Os +.Dt CTM 5 +.Sh NAME +.Nm ctm +.Nd source code mirror system + +.Sh DESCRIPTION +The +.Nm ctm +system uses a specific file format, called a CTM delta. + +CTM deltas consist of control lines and data chunks. Each control +line starts with the letters +.Dq CTM , +followed by a CTM statement and control data, and continues up to +the end of line. + +The CTM statements are as follows. + +.Bl -tag -width indent + +.It _BEGIN Ar version name number timestamp prefix + +This is the overall begin of a CTM delta file. The +.Ar version +field must match the program version +.Pq currently 2.0 . +.Ar Name +is the name and +.Ar number +the sequence number of the CTM service, it is matched against the file +.Pa .ctm_status +to see if the delta has already been applied. +.Ar Timestamp +contains the year, month, day, hour, minute, and second of the +time of delta creation for reference +.Po +followed by the letter +.Sq Z +meaning this is a UTC timestamp +.Pc . +The +.Ar prefix +field is currently always +.Sq \&. . + +.It _END Ar md5 + +This statement ends the CTM delta, the global +.Ar md5 +checksum is matched against the entire delta to ensure it has been +transfered correctly. + +.It \&FM Ar name uid gid mode md5 count + +Make the file +.Ar name , +the original file had the uid +.Ar uid +.Pq numerical, decimal , +the gid +.Ar gid +.Pq numerical, decimal , +mode +.Ar mode +.Pq numerical, octal , +and the MD5 checksum +.Ar md5 . + +The following +.Ar count +bytes data are the contents of the new file. + +.It \&FS Ar name uid gid mode md5before md5after count + +Substitute the contents of file +.Ar name , +the original file had the new uid +.Ar uid +.Pq numerical, decimal , +the new gid +.Ar gid +.Pq numerical, decimal , +new mode +.Ar mode +.Pq numerical, octal , +the old MD5 checksum +.Ar md5before , +and the new MD5 checksum +.Ar md5after . + +The following +.Ar count +bytes data are the contents of the new file. + +File substitution is used if the commands to edit a file would exceed +the total file length, so substituting it is more efficient. + + +.It \&FN Ar name uid gid mode md5before md5after count + +Edit the file +.Ar name . +The arguments are as above, but the data sections contains an +.Xr ed 1 +like script to edit the file contents. + +.It \&FR Ar name md5 + +Remove the file +.Ar name , +which must match the MD5 checksum +.Ar md5 . + + +.It \&AS Ar name uid gid mode + +The original file +.Ar name +changed its owner to +.Ar uid , +its group to +.Ar gid , +and/or its mode to +.Ar mode . + + +.It \&DM Ar name uid gid mode + +The directory +.Ar name +is to be created, it had originally the owner +.Ar uid , +group +.Ar gid , +and mode +.Ar mode . + + +.It \&DR name + +The directory +.Ar name +is to be removed. + + +.El + +.Sh EXAMPLES + +In the following example, long lines have been folded to make them +printable +.Pq marked by backslashes . + +.Bd -literal + +CTM_BEGIN 2.0 cvs-cur 485 19950324214652Z . +CTMFR src/sys/gnu/i386/isa/scd.c,v 5225f13aa3c7e458f9dd0d4bb637b18d +CTMFR src/sys/gnu/i386/isa/scdreg.h,v e5af42b8a06f2c8030b93a7d71afb223 +CTMDM src/sys/gnu/i386/isa/Attic 0 552 775 +CTMFS .ctm_status 545 552 664 d9ccd2a84a9dbb8db56ba85663adebf0 \\ +e2a10c6f66428981782a0a18a789ee2e 12 +cvs-cur 485 + +CTMFN CVSROOT/commitlogs/gnu 545 552 664 \\ +5d7bc3549140d860bd9641b5782c002d 7fb04ed84b48160c9b8eea84b4c0b6e3 394 +a6936 21 +ache 95/03/24 09:59:50 + + Modified: gnu/lib/libdialog kernel.c prgbox.c + Log: +[...] +CTM_END 74ddd298d76215ae45a077a4b6a74e9c + +.Ed + +.Sh SEE ALSO + +.Xr ctm 1 ; +.Xr ed 1 . + +.Sh HISTORY + +The CTM system has been made publically available in FreeBSD 2.1. + +.Sh AUTHORS + +The CTM system has been designed and implemented by +Poul-Henning Kamp +.Aq phk@FreeBSD.org . +