From owner-svn-doc-head@FreeBSD.ORG Wed Feb 12 21:01:00 2014 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 065C4F8D; Wed, 12 Feb 2014 21:01:00 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id D75091CC8; Wed, 12 Feb 2014 21:00:59 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s1CL0xoE085738; Wed, 12 Feb 2014 21:00:59 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s1CL0xpL085737; Wed, 12 Feb 2014 21:00:59 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201402122100.s1CL0xpL085737@svn.freebsd.org> From: Dru Lavigne Date: Wed, 12 Feb 2014 21:00:59 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r43887 - head/en_US.ISO8859-1/books/handbook/mirrors X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 12 Feb 2014 21:01:00 -0000 Author: dru Date: Wed Feb 12 21:00:59 2014 New Revision: 43887 URL: http://svnweb.freebsd.org/changeset/doc/43887 Log: Finish initial pass through CTM chapter. Sponsored by: iXsystems Modified: head/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml Wed Feb 12 19:38:42 2014 (r43886) +++ head/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml Wed Feb 12 21:00:59 2014 (r43887) @@ -148,7 +148,7 @@ 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 - update is 10-50K in size and rarely there will be an update + updates is 10-50K in size, and there will occasionally be an update larger than 100K+. When using CTM to track &os; development, @@ -172,8 +172,7 @@ email. FTP deltas can be obtained from the following mirror sites. - Download the relevant directory and read its - README. When using anonymous FTP to obtain CTM deltas, + When using anonymous FTP to obtain CTM deltas, select a geographically close mirror. In case of problems, contact the &a.ctm-users.name; mailing list. @@ -228,10 +227,10 @@ To instead receive deltas through email, subscribe to one of the - CTM distribution lists. - &a.ctm-src-cur.name; supports the entire source tree, + ctm-src distribution lists available from + http://lists.freebsd.org/mailman/listinfo. For example, &a.ctm-src-cur.name; supports the HEAD of the development - branch, and &a.ctm-src-9.name; supports the 9.X release branch. + branch and &a.ctm-src-9.name; supports the 9.X release branch. As CTM updates arrive through email, @@ -253,154 +252,142 @@ - Using <application>CTM</application> for the First - Time + <application>CTM</application> Usage Before CTM - deltas can be used, a starting point for the - deltas must be produced from an empty directory. - An initial Empty delta is used to start - the local CTM-supported tree. - - 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). + 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 your initial seed. - Empty is an empty directory. As a rule a + 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. By the way, they are large! 70 to 80 + 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. - Once you have picked a base delta to start from, you will - also need all deltas with higher numbers following it. - - - - Using <application>CTM</application> in Your Daily - Life - - To apply the deltas, simply say: - - &prompt.root; cd /where/ever/you/want/the/stuff -&prompt.root; 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 + 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: + + &prompt.root; cd /directory/to/store/the/stuff +&prompt.root; ctm -v -v /directory/which/stores/the/deltas/src-xxx.* + + Multiple deltas can be applied at one time as they + will be processed one at a time and any deltas that are already + applied will be ignored. CTM understands deltas which + have been put through gzip, which 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 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. - - 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. + To + verify a delta without applying it, include . + CTM will not actually touch + the local tree but will instead verify the integrity of the delta + to see if it would apply cleanly. Refer to &man.ctm.1; for + more information about available switches 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 + something bad happens. - Keeping Your Local Changes + Keeping Local Changes - As a developer one would like to experiment with and - change files in the source tree. + Developers often experiment with and + change files in thier local 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. + 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. - Other Interesting <application>CTM</application> + <title>Other <application>CTM</application> Options - - Finding Out Exactly What Would Be Touched by an - Update - - You can determine the list of changes that - CTM will make on your source - repository using the 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. - + + + Finding Out Exactly What Would Be Touched by an + Update - - Making Backups Before Updating + + To determine the list of changes that + CTM will make to the local source + repository, use . This option is useful for creating logs of the + changes or when performing pre- or post-processing on any of the modified files. + + - Sometimes you may want to backup all the files that - would be changed by a CTM - update. + + Making Backups Before Updating - Specifying the option - causes CTM to backup all files - that would be touched by a given + + To backup all of the files that + would be changed by a CTM + update, specify . This option + tells CTM to backup all files + touched by the applied CTM delta to backup-file. - + + - - Restricting the Files Touched by an Update + + Restricting the Files Touched by an Update - Sometimes you would be interested in restricting the + + To restrict 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 - and options. + to extract just a few files from a + sequence of deltas, + filtering regular expressions can be specified using + , which specifies which files to process, or , which specifies which files to ignore. For example, to extract an up-to-date copy of - lib/libc/Makefile from your collection - of saved CTM deltas, run the - commands: + lib/libc/Makefile from a collection + of saved CTM deltas: - &prompt.root; cd /where/ever/you/want/to/extract/it/ -&prompt.root; ctm -e '^lib/libc/Makefile' ~ctm/src-xxx.* + &prompt.root; cd /directory/to/extract/to/ +&prompt.root; ctm -e '^lib/libc/Makefile' /directory/which/stores/the/deltas/src-xxx.* For every file specified in a - CTM delta, the - and options are - applied in the order given on the command line. The file is + CTM delta, + and 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 the and - options are applied to it. - + marked as eligible after all and + options are applied. + + + - +