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 <phk@FreeBSD.org> for
more information should you wish to use CTM for other things.

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.

FTP the relevant directory and fetch the README file, starting from there.

If you wish to get your deltas via email:

Send email to <majordomo@FreeBSD.org>
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 <ctm-announce@FreeBSD.org>
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 <majordomo@FreeBSD.org>
with a single line of subscribe
ctm-announce to get added to the list.

Before you can start using
CTM deltas, you will need to get to a starting point
for the deltas produced subsequently to it.

First you should determine what you already have.
Everyone can 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 ``started'' deltas be
distributed on the CD for your convenience, however, this
does not currently happen.

Since the trees are many tens of megabytes, you should
prefer to start from something already at hand. If you have
a -RELEASE CD, you can copy or extract an initial source
from it. This will save a significant transfer of data.

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 produced every 100 deltas. By the way, they are large!
25 to 30 Megabytes of gzip'd 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 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 is 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 behavior 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.

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.