<!--
     The FreeBSD Documentation Project
-->

<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;
]>

<article>
  <articleinfo>
    <title>CVSup Advanced Points</title>

    <authorgroup>
      <author>
	<firstname>Salvo</firstname>
	<surname>Bartolotta</surname>

	<affiliation>
	  <address><email>bartequi@neomedia.it</email></address>
	</affiliation>
      </author>
    </authorgroup>

    <pubdate>$FreeBSD$</pubdate>

    <abstract>
      <para>The present article assumes a basic understanding of CVSup
        operation. It documents several delicate issues connected with 
	source synchronization via CVSup, viz. effective solutions to
	the problem of stale files as well as special source updating
	cases; which issues are likely to cause apparently inexplicable
	troubles.</para>
    </abstract>
  </articleinfo>

  <sect1 id="preface">
    <title>Preface</title>
    
      <para>This document is the fruit of the author's attempts to    
	fully understand the niceties of cvsup &amp; source updating.&nbsp;:-)
	While the author has made every effort to make these pages 
        as informative and correct as possible, he is only human and 
	may have made all sorts of typos, mistakes, etc.  He will be
	very grateful for any comments and/or suggestions you send to
	his e-mail address, <email>bartequi@neomedia.it</email>.</para>
  </sect1>

 
  <sect1 id="introduction">
    <title>Introduction</title>

      <para>If you have visited
	<ulink url="http://www.polstra.com/">John Polstra's site</ulink>
        and read
        <ulink url="http://www.polstra.com/projects/freeware/CVSup/faq.html">his
FAQ</ulink>,
        you may have noticed Question 12 &amp; 13.</para>

      <para>When updating any collection of sources (eg 
	<filename>/usr/ports</filename>), &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
        (<filename>/usr/ports</filename>), the related checkouts file
        is <filename>/usr/sup/ports-all/checkouts.cvs:.</filename> if
        your base is <filename>/usr</filename>.</para>

      <para>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. They 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.</para>

     <para>It is therefore recommended that you adopt the two-step procedure
       outlined in the Cvsup FAQ (cf Q12, Q13); in subsequent sections, you
       will be given interesting and instructive concrete examples.</para>
  </sect1>

  <sect1 id="script">
    <title>A useful python script: cvsupchk</title>

      <para>Alternatively, in order to examine your sources for 
	inconsistencies, you may wish to utilize the cvsupchk python 
	script; which script is currently found in 
	<filename>/usr/ports/net/cvsup/work/cvsup-16.1/contrib/cvsupchk</filename>,
	together with a nice <filename>README</filename>. Prerequisites:</para>

        <orderedlist>
           <listitem>
             <para><literal>/usr/ports/net/cvsup</literal> &prompt.root;
<userinput> make extract</userinput></para>
           </listitem>

           <listitem>
             <para>python (also found in the ports collection :-))</para>
           </listitem>

           <listitem>
             <para>a checkouts file for your collection of sources.</para>
           </listitem>
         </orderedlist>

      <para>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 <filename>/usr/ports</filename>),
	you can check them thus:</para>

        <screen>&prompt.user; <filename>/path/to/</filename><userinput>cvsupchk -d /usr -c /usr/sup/ports-all/checkouts.cvs:. | more</userinput></screen>

      <para>If you want to check your RELENG_4 sources:</para>

        <screen>&prompt.user; <filename>/path/to/</filename><userinput>cvsupchk -d /usr -c /usr/sup/src-all/checkouts.cvs:RELENG_4 | more</userinput></screen>

      <para>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.</para>

      <para>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.</para>
  </sect1>

  <sect1 id="examples">
    <title>Examples of more advanced source management</title>

      <sect2>
        <title>How to safely change tags when updating
<literal>src-all.</literal></title>

        <para>If you specify eg tag=A in your supfile, cvsup will create
	  a checkouts file called <filename>checkouts.cvs:A</filename>: 
	  for instance, if tag=RELENG_4, a checkouts file called
          <filename>checkouts.cvs:RELENG_4</filename> is generated. 
           This file will be used to retrieve and/or store information
           identifying your 4-STABLE sources.</para>

         <para>When tracking <literal>src-all</literal>, 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 
	   <filename>checkouts.cvs:A</filename>, the following actions
	   should be performed:</para>

            <orderedlist>
              <listitem>
                <para>&prompt.root; <userinput>mv checkouts.cvs:A
checkouts.cvs:B</userinput>
                  (This provides the subsequent step with the appropriate
                  checkouts file)</para>
              </listitem>

              <listitem>
                <para>write a supfile whose collection line reads:</para>
                  <programlisting>src-all tag=B</programlisting>
              </listitem>

              <listitem>
                <para>cvsup your sources using the new supfile.</para>
              </listitem>
            </orderedlist>

         <para>Cvsup will look for <filename>checkouts.cvs:B</filename> 
	   -- in that the target is B; that is, cvsup will make use of 
	   the information contained therein to correctly manage your 
	   sources.</para>

         <para>The benefits:</para>

           <itemizedlist>
              <listitem>
                <para>the sources are dealt with correctly (in particular,
		  no stale files)</para>
              </listitem>

              <listitem>
                <para>less load is placed on the server, in that cvsup 
		  operates in the most efficient way.</para>
              </listitem>
           </itemizedlist>


         <para>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.</para>
       </sect2>

       <sect2>
         <title>Updating to the same tag as of a different date</title>

         <para>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:</para>

           <orderedlist>
             <listitem>
               <para>write a supfile whose collection line reads:</para>
                 <programlisting>src-all tag=A date=D</programlisting>
             </listitem>

             <listitem>
               <para>update your sources using the new supfile</para>
             </listitem>
           </orderedlist>

         <para>Whether the new date precedes that of the last sync
	   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:</para>


         <programlisting>src-all tag=RELENG_4 date=2000.08.27.10.00.00</programlisting>

         <note><para>The format of a date is rigid. You have to specify 
	   all the components of the date: century (20, ie the 20th 
	   century, must be supplied whereas 19, the past century, can 
	   be omitted), year, month, day, hour, minutes, seconds -- as 
	   shown in the above example.  For more information, please 
	   see &man.cvsup.1;.</para></note>

         <para>Whether or not a date is specified, the checkouts file 
	   is called <filename>checkouts.cvs:A</filename> (eg
           <filename>checkouts.cvs:RELENG_4</filename>). 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.</para>
       </sect2>


       <sect2>
         <title>Updating your ports collection for the first time</title>

         <para>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 sync operation, the date field must be removed;
           all subsequent updates will be carried out smoothly.</para>

         <para>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. :-)</para>
      </sect2>
   </sect1>
</article>
