CTM is a method for keeping a remote directory tree in sync with a central one. It is built into FreeBSD and can be used to synchronize a system with FreeBSD's source repositories. It supports synchronization of an entire repository or just a specified set of branches.
CTM is specifically designed for use on lousy or non-existent TCP/IP connections and provides the ability for changes to be automatically sent by email. It requires the user to obtain up to three deltas per day for the most active branches. Update sizes are always kept as small as possible and are typically less than 5K. About one in very ten updates is 10-50K in size, and there will occasionally be an update larger than 100K+.
When using CTM to track FreeBSD development, refer to the caveats related to working directly from the development sources rather than a pre-packaged release. These are discussed in Tracking a Development Branch.
Little documentation exists on the process of creating deltas or using CTM for other purposes. Contact the ctm-users mailing list for answers to questions on using CTM.
The “deltas” used by CTM can be obtained either through anonymous FTP or email.
FTP deltas can be obtained from the following mirror sites. When using anonymous FTP to obtain CTM deltas, select a mirror that is geographically nearby. In case of problems, contact the ctm-users mailing list.
To instead receive deltas through email, subscribe to one
of the ctm-src distribution lists available
from http://lists.freebsd.org/mailman/listinfo.
For example, ctm-src-cur supports the head
development branch and ctm-src-9 supports the 9.X
release branch.
As CTM updates arrive through
email, use ctm_rmail to unpack and apply
them. This command can be run directly from an entry in
/etc/aliases in order to automate this
process. Refer to ctm_rmail(1) for more details.
Regardless of the method which is used to get deltas, CTM users should subscribe to the ctm-announce mailing list as this is the only mechanism by which CTM announcements are posted.
Before CTM deltas can be used for the first time, a starting point must be produced.
One method is to apply a “starter” delta to
an empty directory. A starter delta can be recognized by the
XEmpty in its name, such as
src-cur.3210XEmpty.gz. The designation
following the X corresponds to the origin
of the initial “seed”, where
Empty is an empty directory. As a rule,
a base transition from Empty is produced
every 100 deltas. Be aware that starter deltas are large and
70 to 80 Megabytes of gzip'd data is common
for the XEmpty deltas.
Another method is to copy or extract an initial source from a RELEASE media as this can save a significant transfer of data from the Internet.
Once a base delta has been created, apply all deltas with higher numbers. To apply the deltas:
#cd /directory/to/store/the/stuff#ctm -v -v /directory/which/stores/the/deltas/src-xxx.*
Multiple deltas can be applied with a single command as
they will be processed one at a time and any deltas that are
already applied will be ignored.
CTM understands
gzip compressed deltas, which saves disk
space.
To verify a delta without applying it, include
-c in the command line.
CTM will not actually modify the
local tree but will instead verify the integrity of the delta
to see if it would apply cleanly. Refer to ctm(1) for
more information about available options and an overview of
the process CTM uses when applying
deltas.
To keep the local source tree up-to-date, every time a new delta becomes available, apply it through CTM.
Once applied, it is recommended to not delete the deltas if it is a burden to download them again. This way, a local copy is available in case it is needed for future disaster recovery.
Developers often experiment with and
change files in their local source tree.
CTM supports local modifications in
a limited way: before checking for the presence of a file,
it first looks for a file with the same name and a
.ctm extension. If this file exists,
CTM will operate on it instead of
the original filename.
This behavior provides a simple way to maintain local
changes. Before modifying a file, make a copy with a
.ctm suffix. Make any changes to the
original filename, knowing that
CTM will only apply updates to the
file with the .ctm suffix.
To determine the list of changes that
CTM will make to the local
source repository, use -l. This option
is useful for creating logs of the changes or when
performing pre- or post-processing on any of the
modified files.
To backup all of the files that would be changed by
a CTM update, specify
-B
. This
option tells CTM to backup
all files touched by the applied
CTM delta to
backup-filebackup-file.
To restrict the scope of a given
CTM update, or to extract
just a few files from a sequence of deltas, filtering
regular expressions can be specified using
-e, which specifies which files to
process, or -x, which specifies which
files to ignore.
For example, to extract an up-to-date copy of
lib/libc/Makefile from a collection
of saved CTM deltas:
#cd /directory/to/extract/to/#ctm -e '^lib/libc/Makefile' /directory/which/stores/the/deltas/src-xxx.*
For every file specified in a
CTM delta,
-e and -x are
applied in the order given on the command line. A file
is processed by CTM only if
it is marked as eligible after all -e
and -x options are applied.
All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/
Questions that are not answered by the
documentation may be
sent to <[email protected]>.
Send questions about this document to <[email protected]>.