Contributed by Poul-Henning Kamp
<[email protected]>. Updated 19-October-1997.
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
trees, though other people may find it useful for other purposes as
time goes by. Little, if any, documentation currently exists at
this time on the process of creating deltas, so talk to Poul-Henning Kamp
<[email protected]>
for more information should you wish to use CTM for other things.
CTM?CTM will give you a local copy of the FreeBSD source trees.
There are a number of ``flavors'' of the tree available. Whether
you wish to track the entire cvs tree or just one of the branches,
CTM can provide you the information.
If you are an active developer on FreeBSD, but have lousy
or non-existent TCP/IP connectivity, or simply wish to have the
changes automatically sent to you, CTM was made for you.
You will need to obtain up to three deltas per day for the most
active branches. However, you should consider having them sent
by automatic email. The sizes of the updates are
always kept as small as possible. This is typically less than 5K,
with an occasional (one in ten) being 10-50K and every now and
then a biggie of 100K+ or more coming around.
You will also need to make yourself aware of the various caveats related to working directly from the development sources rather than a pre-packaged release. This is particularly true if you choose the ``current'' sources. It is recommended that you read Staying current with FreeBSD.
CTM?You will need two things: The ``CTM'' program and the initial
deltas to feed it (to get up to ``current'' levels).
The CTM program has been part of FreeBSD ever since version 2.0
was released, and lives in /usr/src/usr.sbin/ if you
have a copy of the source online.CTM
If you are running a pre-2.0 version of FreeBSD, you can fetch the
current CTM sources directly from:
ftp://ftp.FreeBSD.ORG/pub/FreeBSD/FreeBSD-current/src/usr.sbin/ctm
The ``deltas'' you feed CTM can be had two ways, FTP or e-mail.
If you have general FTP access to the Internet then the following
FTP sites support access to CTM:
ftp://ftp.FreeBSD.ORG/pub/FreeBSD/CTM
or see section mirrors.
FTP the relevant directory and fetch the README file,
starting from there.
If you may wish to get your deltas via email:
Send email to <[email protected]> to subscribe to one of the CTM
distribution lists. ``ctm-cvs-cur'' supports the entire cvs tree.
``ctm-src-cur'' supports the head of the development branch.
``ctm-src-2_2'' supports the 2.2 release branch, etc.
(If you do not know how to subscribe
yourself using majordomo, send a message first containing the
word ``help'' - it will send you back usage instructions.)
When you begin receiving your CTM updates in the mail, you may
use the ctm_rmail program to unpack and apply them. You
can actually use the ctm_rmail program directly from a entry
in /etc/aliases if you want to have the process run in a
fully automated fashion. Check the ctm_rmail man page for more
details.
NOTE: No matter what method you use to get the CTM
deltas, you should subscribe to the [email protected]
mailing list. In the future, this will be the only place where
announcements concerning the operations of the CTM system will be
posted. Send an email to <[email protected]> with a single
line of ``subscribe ctm-announce'' to get added to the list.
CTM for the first timeBefore you can start using CTM deltas, you will need to get a
to a starting point for the deltas produced subsequently to it.
First you should determine what you already have. Everyone should
start from an ``Empty'' directory. You must use an initial ``Empty''
delta to start off your CTM supported tree. At some point
it is intended that one of these ``starter'' deltas be distributed
on the CD for your convenience. This does not currently happen,
however.
You can recognize these ``starter'' deltas by the ``X'' appended
to the number (src-cur.3210XEmpty.gz for instance).
The designation following the ``X'' corresponds to the origin
of your initial ``seed''. ``Empty'' is an empty directory.
As a rule a base transition from ``Empty'' is producted
every 100 deltas. By the way, they are large! A few tens of
Megabytes of gzip'ed data is common for the ``XEmpty'' deltas.
Once you've picked a base delta to start from, you will also need all deltas with higher numbers following it.
CTM in your daily lifeTo apply the deltas, simply say:
cd /where/ever/you/want/the/stuff
ctm -v -v /where/you/store/your/deltas/src-xxx.*
CTM understands deltas which have been put through gzip,
so you do not need to gunzip them first, this saves disk space.
Unless it feels very secure about the entire process, CTM will
not touch your tree. To verify a delta you can also use the
``-c'' flag and CTM will not actually touch your tree; it will
merely verify the integrity of the delta and see if it would apply
cleanly to your current tree.
There are other options to 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 mind on what options should do what, how and when...
That's really all there is to it. Every time you get a new delta,
just run it through CTM to keep your sources up to date.
Do not remove the deltas if they are hard to download again. You
just might want to keep them around in case something bad happens.
Even if you only have floppy disks, consider using fdwrite to
make a copy.
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
foo, it first looks for foo.ctm. If this
file exists, CTM will operate on it instead of foo.
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 .ctm suffix. Then you can freely hack
the code, while CTM keeps the .ctm file up-to-date.
You can determine the list of changes that CTM will make on your
source repository using the ``-l'' option to CTM.
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 :-).
Sometimes you may want to backup all the files that would be changed by a CTM update.
Specifying the ``-B backup-file'' option causes
CTM to backup all files that would be touched by a given CTM
delta to backup-file.
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.
You can control the list of files that CTM would operate on by
specifying filtering regular expressions using the
``-e'' and ``-x'' options.
For example, to extract an up-to-date copy of
lib/libc/Makefile from your collection of saved CTM deltas,
run the commands:
cd /where/ever/you/want/to/extract/it/
ctm -e '^lib/libc/Makefile' ~ctm/src-xxx.*
For every file specified in a CTM delta, the ``-e'' and
``-x'' 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 ``-e'' and
``-x'' options are applied to it.
CTMTons of them:
CTM, they became confusing and
counter intuitive.The bad news is that I am very busy, so any help in doing this will be most welcome. And do not forget to tell me what you want also...
All the ``DES infected'' (e.g. export controlled) source is not
included. You will get the ``international'' version only. If
sufficient interest appears, we will set up a ``sec-cur''
sequence too.
There is a sequence of deltas for the ports collection too,
but interest has not been all that high yet. Tell me if you want
an email list for that too and we will consider setting it up.
<[email protected]>for his pointed pen and invaluable comments.
<[email protected]>for patience.
wrote ctm_[rs]mail, much appreciated.
<[email protected]>for being so stubborn that I had to make it better.
I hope you like it...