From owner-freebsd-doc Fri Sep 7 18:40:15 2001 Delivered-To: freebsd-doc@freebsd.org Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by hub.freebsd.org (Postfix) with ESMTP id 5101E37B407 for ; Fri, 7 Sep 2001 18:40:03 -0700 (PDT) Received: (from gnats@localhost) by freefall.freebsd.org (8.11.4/8.11.4) id f881e3N80802; Fri, 7 Sep 2001 18:40:03 -0700 (PDT) (envelope-from gnats) Date: Fri, 7 Sep 2001 18:40:03 -0700 (PDT) Message-Id: <200109080140.f881e3N80802@freefall.freebsd.org> To: freebsd-doc@freebsd.org Cc: From: Salvo Bartolotta Subject: Re: docs/24662: too many questions about source management bloat freebsd lists Reply-To: Salvo Bartolotta Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org The following reply was made to PR docs/24662; it has been noted by GNATS. From: Salvo Bartolotta To: Murray Stokely Cc: freebsd-gnats-submit@FreeBSD.org, cvsupbugs@polstra.com Subject: Re: docs/24662: too many questions about source management bloat freebsd lists Date: Sat, 08 Sep 2001 03:30:17 +0200 (CEST) This message is in MIME format. ---MOQ999912617bf28d22212d6ba57727d5d15660290b8 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 8bit Here is a patch, as promised. I exchanged a couple of e-mail messages with John Polstra on this subject a few months ago; I am sending him the draft so that he may also be able to spot any bugs and give suggestions. -- Salvo ---MOQ999912617bf28d22212d6ba57727d5d15660290b8 Content-Type: text/plain; name="patch"; charset=ISO-8859-1 Content-Transfer-Encoding: 8bit Content-Disposition: inline; filename="patch" =================================================================== RCS file: /myjunk/home/ncvs/doc/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml,v retrieving revision 1.153 diff -u -r1.153 chapter.sgml --- chapter.sgml 2001/09/05 00:29:19 1.153 +++ chapter.sgml 2001/09/08 00:22:40 @@ -3910,6 +3910,213 @@ + + + + + + Salvo + Bartolotta + Contributed by + + + + + Advanced Points + + + Introduction + + If you have visited John Polstra's site + and read + his FAQ, + you may probably have noticed Question 12 & 13. + + When updating any collection of sources (eg /usr/ports), + &man.cvsup.1; makes use of the related checkouts file in order to + perform the updating process in the most efficient and correct way. + In this example (/usr/ports), the related checkouts + file is /usr/sup/ports-all/checkouts.cvs:. if + your base is /usr. + + A checkouts file contains information on the current status of your + sources -- in a way, a sort of "photograph". This significant information + enables cvsup to retrieve updates most effectively. Further, and maybe + more important, it enables cvsup to correctly manage your sources by + locally deleting any files no longer present in the repository, thus + leaving no stale files on your system. In fact, without a checkouts file, + cvsup would NOT know which files your collection was composed of (cf + &man.cvsup.1; and the fallback method for details); as a result, it + could NOT delete on your system those files no longer present in the + repository. These files would remain on your system (stale files), and + might cause you subtle build failures or other trouble. For example, + this problem is likely to occur if you first update your ports + collection several weeks after you have got(ten) your installation + CDs. + + It is therefore recommended that you adopt the two-step procedure + outlined in the Cvsup FAQ (cf Q12, Q13); later, you will be given + interesting and instructive concrete examples. + + + An useful python script: cvsupchk + + Alternatively, in order to examine your sources for inconsistencies, + you may wish to utilize the cvsupchk python script; which script is + currently found in /usr/ports/net/cvsup/work/cvsup-16.1/contrib/cvsupchk, + together with a nice README. Prerequisites: + + + + /usr/ports/net/cvsup &prompt.root; make extract + + + + python (also found in the ports collection :-)) + + + + a checkouts file for your collection of sources. + + + + If you are updating your sources for the very first time, of course + you do not have a checkouts file. After installing python and updating + your sources (eg /usr/ports), you can check them + thus: + + &prompt.user; /path/to/cvsupchk -d /usr -c /usr/sup/ports-all/checkouts.cvs:. | more + + If you want to check your RELENG_4 sources: + + &prompt.user; /path/to/cvsupchk -d /usr -c /usr/sup/src-all/checkouts.cvs:RELENG_4 | more + + In each case, cvsupchk will inspect your sources for inconsistencies + by utilizing the information contained in the related checkouts file. + Such anomalies as deleted files being present (aka stale files), missing + checked out files, extra RCS files, and dead directories, will be + printed to standard output. + + In the next section, we will provide important, typical examples of + source updating; which examples will show you the role of checkouts + files and the dangers of negligent source management. + + + + Examples of more advanced source management + + + How to safely change tags when updating <literal>src-all.</literal> + + If you specify eg tag=A in your supfile, cvsup will create a + checkouts file called checkouts.cvs:A: for + instance, if tag=RELENG_4, a checkouts file called + checkouts.cvs:RELENG_4 is generated. This file + will be used to retrieve and/or store identification information + on your 4-STABLE sources. + + When tracking src-all, if you wish to pass from tag=A to tag=B + (A less/greater than B not making any difference) and if your + checkouts file is checkouts.cvs:A, the + following actions should be performed: + + + + &prompt.root; mv checkouts.cvs:A checkouts.cvs:B + (This provides the subsequent step with the appropriate + checkouts file) + + + + write a supfile whose collection line reads: + src-all tag=B + + + + cvsup your sources using the new supfile. + + + + Cvsup will look for checkouts.cvs:B -- in + that the target is B; that is, cvsup will make use of the information + contained therein to correctly manage your sources. + + The benefits: + + + + the sources are dealt with correctly (in particular, no + stale files) + + + + less load is placed on the server, in that cvsup operates + in the most efficient way. + + + + For example, A=RELENG_4, B=. The period in "B=." means -CURRENT. + This is a rather typical update, from 4-STABLE to -CURRENT. While it + is straightforward to "downgrade" your sources (eg from -CURRENT to + -STABLE), downgrading a system is quite another matter. You are + STRONGLY advised not to attempt such an operation, unless you know + exactly what you are doing. + + + + Updating to the same tag as of a different date + + If you wish to switch from "tag=A" to "tag=A" as of a different + GMT date (say, "date=D"), you will execute the following: + + + + write a supfile whose collection line reads: + src-all tag=A date=D + + + + update your sources using the new supfile + + + + Whether the new date precedes that of the last synch operation + with tag=A or not, it is immaterial. For example, in order to + specify the date "August 27, 2000, 10:00:00 GMT" you write the + line: + + src-all tag=RELENG_4 date=2000.08.27.10.00.00 + + N.B. The format of a date is rigid. You have to specify all + the components of the date: century (19 for the 19th or 20 for the + 20th), year, month, day, hour, minutes, seconds -- as shown in the + above example. For more information, please see &man.cvsup.1;. + + Whether or not a date is specified, the checkouts file is called + checkouts.cvs:A (eg + checkouts.cvs:RELENG_4). As a result, no + particular action is needed in order to revert to the previous state: + you have to modify the date in the supfile, and csvup again. + + + + Updating your ports collection for the first time + + Since ports are tagged "." (ie -CURRENT), you can correctly "sync" + them for the first time by adding the date keyword (cf &man.cvsup.1; + for the exact format): you should specify a date as close as possible + to that of "shipping" of your ports tree. After cvsup has correctly + created the ports checkouts file, which is precisely the goal of + this first special synch operation, the date field must be removed; + all subsequent updates will be carried out smoothly. + + If you have been reading the apparently nit-picking remarks in + these sections, you will probably have recognized the potential for + scr^Wtrouble in a source updating process. A number of people have + actually run into problems. You have been warned. :-) + + + ---MOQ999912617bf28d22212d6ba57727d5d15660290b8-- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message