<para><anchor id="repomeisters">The only ones able to directly

      fiddle the repository bits on the repository hosts are the

      repomeisters.  To enforce this, there are no login shells

      available on the repository machines, except to the

      repomeisters.</para>

    <note>

      <para>Depending on the affected area of the repository, you

	should send your request for a repocopy to one of the

	following email addresses.  Email sent to these addresses will

	be forwarded to the appropriate repomeisters.</para>

      <itemizedlist>

	<listitem><para>pcvs@ - regarding <filename class="directory">

	    /home/pcvs</filename>, the ports

	  repository</para></listitem>

	<listitem><para>projcvs@ - regarding <filename

	      class="directory"> /home/projcvs</filename>, the

	  third party projects repository</para></listitem>

      </itemizedlist>

    </note>

    <para>The &os; repositories are currently split into two distinct

      parts, namely <literal>ports</literal> and

      <literal>projects</literal>.  These are combined under a single

      <literal>CVSROOT</literal> when distributed via

      <application>CVSup</application> for the convenience of our

      users.  The <literal>src</literal> tree is automatically

      exported to CVS for compatibility reasons only (e.g.,

      <application>CVSup</application>).  The <quote>official</quote>

      <literal>src</literal> repository is not stored in

      <application>CVS</application> but in Subversion.  The official

      and exported trees are not necessarily equal.</para>

    <para>The CVS repositories are hosted on the repository machines.

      Currently, each of the repositories above reside on the same

      physical machine, <hostid

	role="hostname">ncvs.FreeBSD.org</hostid>, but to allow for

      the possibility of placing each on a separate machine in the

      future, there is a separate hostname for each that committers

      should use.  Additionally, each repository is stored in a

      separate directory.  The following table summarizes the

      situation.</para>

    <table frame="none" id="cvs-repositories-and-hosts">

      <title>&os; CVS Repositories, Hosts and Directories</title>

      <tgroup cols="3">

	<thead>

	  <row>

	    <entry>Repository</entry>

	    <entry>Host</entry>

	    <entry>Directory</entry>

	  </row>

	</thead>

	<tbody>

	  <row>

	    <entry>ports</entry>

	    <entry>pcvs.FreeBSD.org</entry>

	    <entry>/home/pcvs</entry>

	  </row>

	  <row>

	    <entry>projects</entry>

	    <entry>projcvs.FreeBSD.org</entry>

	    <entry>/home/projcvs</entry>

	  </row>

	</tbody>

      </tgroup>

    </table>

    <para>CVS operations are done remotely by setting the

      <envar>CVSROOT</envar> environment variable to the appropriate

      host and top-level directory (for example, <hostid

	role="fqdn">pcvs.FreeBSD.org</hostid><literal>:</literal><filename>/home/pcvs</filename>),

      and doing the appropriate check-out/check-in operations.  Many

      committers define aliases which expand to the correct

      <application>cvs</application> invocation for the appropriate

      repository.  For example, a &man.tcsh.1; user may add the

      following to their <filename>.cshrc</filename> for this

      purpose:</para>

    <programlisting>alias pcvs cvs -d <replaceable>user</replaceable>@pcvs.FreeBSD.org:/home/pcvs

alias projcvs cvs -d <replaceable>user</replaceable>@projcvs.FreeBSD.org:/home/projcvs</programlisting>

    <para>This way they can do all CVS operations locally and use

      <command><replaceable>X</replaceable>cvs commit</command> for

      committing to the official CVS repository.

      Refer to the &man.cvs.1; manual page for usage.</para>

    <note>

      <para>Please do <emphasis>not</emphasis> use <command>cvs

	  checkout</command> or <command>update</command> with the

	official repository machine set as the CVS Root for keeping

	your source tree up to date.  Remote CVS is not optimized for

	network distribution and requires a big work/administrative

	overhead on the server side.  Please use our advanced

	<command>cvsup</command> distribution method for obtaining the

	repository bits, and only do the actual

	<command>commit</command> operation on the repository host.

	We provide an extensive cvsup replication network for this

	purpose, as well as give access to

	<hostid>cvsup-master</hostid> if you really need to stay

	current to the latest changes.  <hostid>cvsup-master</hostid>

	has got the horsepower to deal with this, the repository

	master server does not.  &a.kuriyama; is in charge of

	<hostid>cvsup-master</hostid>.</para>

    </note>

    <para>If you need to use CVS <command>add</command> and

      <command>delete</command> operations in a manner that is

      effectively a &man.mv.1; operation, then a repository copy is in

      order rather than using CVS <command>add</command> and

      <command>delete</command>.  In a repository copy, a <link

	linkend="repomeisters">repomeister</link> will copy the

      file(s) to their new name and/or location and let you know when

      it is done.  The purpose of a repository copy is to preserve

      file change history, or logs.  We in the FreeBSD Project greatly

      value the change history that a version control system gives to

      the project.</para>

    <para>CVS reference information, tutorials, and FAQs can be found

      at: <ulink url="http://www.cvshome.org/docs/"></ulink>.  The

      information in <ulink

	url="http://cvsbook.red-bean.com/cvsbook.html">Karl Fogel's

	chapters from <quote>Open Source Development with

	  CVS</quote></ulink> is also very useful.</para>

    <para>&a.des; also supplied the following <quote>mini

	primer</quote> for CVS.</para>

    <orderedlist>

      <listitem>

	<para>Check out a module with the <command>co</command> or

	  <command>checkout</command> command.</para>

	<screen>&prompt.user; <userinput>cvs checkout shazam</userinput></screen>

	<para>This checks out a copy of the

	  <filename>shazam</filename> module. If there is no

	  <filename>shazam</filename> module in the modules file, it

	  looks for a top-level directory named

	  <filename>shazam</filename> instead.</para>

	<table frame="none">

	  <title>Useful <command>cvs checkout</command>

	    options</title>

	  <tgroup cols=2>

	    <tbody>

	      <row>

		<entry><option>-P</option></entry>

		<entry>Do not create empty directories</entry>

	      </row>

	      <row>

		<entry><option>-l</option></entry>

		<entry>Check out a single level, no

		  subdirectories</entry>

	      </row>

	      <row>

		<entry><option>-r<replaceable>rev</replaceable></option></entry>

		<entry>Check out revision, branch or tag

		  <replaceable>rev</replaceable></entry>

	      </row>

	      <row>

		<entry><option>-D<replaceable>date</replaceable></option></entry>

		<entry>Check out the sources as they were on date

		  <replaceable>date</replaceable></entry>

	      </row>

	    </tbody>

	  </tgroup>

	</table>

	<para>Practical FreeBSD examples:</para>

	<itemizedlist>

	  <listitem>

	    <para>Check out the <filename>Tools</filename> module,

	      which corresponds to

	      <filename>ports/Tools</filename>:</para>

	    <screen>&prompt.user; <userinput>cvs co Tools</userinput></screen>

	    <para>You now have a directory named

	      <filename>ports/Tools</filename> with subdirectories

	      <filename>portbuild</filename>,

	      <filename>scripts</filename>, and

	      <filename>CVS</filename>.</para>

	  </listitem>

	  <listitem>

	    <para>Check out the same files, but with full path:</para>

	    <screen>&prompt.user; <userinput>cvs co ports/Tools</userinput></screen>

	    <para>You now have a directory named

	      <filename>ports</filename>, with subdirectories

	      <filename>CVS</filename> and <filename>Tools</filename>.

	      The <filename>ports/Tools</filename> directory has

	      subdirectories <filename>CVS</filename> and

	      <filename>scripts</filename>, etc.</para>

	  </listitem>

	  <listitem>

	    <para>Check out the directory <filename>Tools</filename>,

	      but none of the subdirectories:</para>

	    <screen>&prompt.user; <userinput>cvs co -l Tools</userinput></screen>

	    <para>You now have a directory named

	      <filename>Tools</filename> with just one subdirectory

	      named <filename>CVS</filename>.</para>

	  </listitem>

	  <listitem>

	    <para>Check out the <filename>Tools</filename> module as

	      it was when support for &os; 5.X was

	      dropped:</para>

	    <screen>&prompt.user; <userinput>cvs co -rRELEASE_5_EOL Tools</userinput></screen>

	    <para>You will not be able to commit modifications, since

	      <literal>RELEASE_5_EOL</literal> is a point in time, not

	      a branch.</para>

	  </listitem>

	  <listitem>

	    <para>Check out the <filename>Tools</filename> module as

	      it was on March 25th, 2009:</para>

	    <screen>&prompt.user; <userinput>cvs co -D'2009-03-25' Tools</userinput></screen>

	    <para>You will not be able to commit modifications.</para>

	  </listitem>

	  <listitem>

	    <para>Check out the <filename>Tools</filename> module as

	      it was one week ago:</para>

	    <screen>&prompt.user; <userinput>cvs co -D'last week' Tools</userinput></screen>

	    <para>You will not be able to commit modifications.</para>

	  </listitem>

	</itemizedlist>

	<para>Note that cvs stores metadata in subdirectories named

	  <filename>CVS</filename>.  Similarly, Subversion stores

	  metadata in subdirectories named

	  <filename>.svn</filename>.</para>

	<para>Arguments to <option>-D</option> and <option>-r</option>

	  are sticky, which means cvs will remember them later, e.g.,

	  when you do a <command>cvs update</command>.</para>

      </listitem>

      <listitem>

	<para>Check the status of checked-out files with the

	  <command>status</command> command.</para>

	<screen>&prompt.user; <userinput>cvs status shazam</userinput></screen>

	<para>This displays the status of the file

	  <filename>shazam</filename> or of every file in the

	  <filename>shazam</filename> directory. For every file, the

	  status is given as one of:</para>

	<informaltable frame="none" pgwide="1">

	  <tgroup cols=2>

	    <tbody>

	      <row>

		<entry>Up-to-date</entry>

		<entry>File is up-to-date and unmodified.</entry>

	      </row>

	      <row>

		<entry>Needs Patch</entry>

		<entry>File is unmodified, but there is a newer

		  revision in the repository.</entry>

	      </row>

	      <row>

		<entry>Locally Modified</entry>

		<entry>File is up-to-date, but modified.</entry>

	      </row>

	      <row>

		<entry>Needs Merge</entry>

		<entry>File is modified, and there is a newer revision

		  in the repository.</entry>

	      </row>

	      <row>

		<entry>File had conflicts on merge</entry>

		<entry>There were conflicts the last time this file

		  was updated, and they have not been resolved

		  yet.</entry>

	      </row>

	    </tbody>

	  </tgroup>

	</informaltable>

	<para>You will also see the local revision and date,

	  the revision number of the newest applicable version

	  (<quote>newest applicable</quote> because if you have a

	  sticky date, tag or branch, it may not be the actual newest

	  revision), and any sticky tags, dates or options.</para>

      </listitem>

      <listitem>

	<para>Once you have checked something out, you can update it

	  with the <command>update</command> command.</para>

	<screen>&prompt.user; <userinput>cvs update shazam</userinput></screen>

	<para>This updates the file <filename>shazam</filename> or the

	  contents of the <filename>shazam</filename> directory to the

	  latest version along the branch you checked out.  If you

	  checked out a <quote>point in time</quote>, it does nothing

	  unless the tags have moved in the repository or some other

	  weird stuff is going on.</para>

	<para>Useful options, in addition to those listed above for

	  <command>checkout</command>:</para>

	<informaltable frame="none" pgwide="1">

	  <tgroup cols=2>

	    <tbody>

	      <row>

		<entry><option>-d</option></entry>

		<entry>Check out any additional missing

		  directories.</entry>

	      </row>

	      <row>

		<entry><option>-A</option></entry>

		<entry>Update to head of main branch.</entry>

	      </row>

	    </tbody>

	  </tgroup>

	</informaltable>

	<para>If you checked out a module with <option>-r</option> or

	  <option>-D</option>, running <command>cvs update</command>

	  with a different <option>-r</option> or <option>-D</option>

	  argument or with <option>-A</option> will select a new

	  branch, revision or date. The <option>-A</option> option

	  clears all sticky tags, dates or revisions whereas

	  <option>-r</option> and <option>-D</option> set new

	  ones.</para>

	<para>Theoretically, specifying <literal>HEAD</literal> as the

	  argument to <option>-r</option> will give you the same

	  result as <option>-A</option>, but that is just

	  theory.</para>

	<para>The <option>-d</option> option is useful if:</para>

	<itemizedlist>

	  <listitem>

	    <para>somebody has added subdirectories to the module

	      you have checked out after you checked it out.</para>

	  </listitem>

	  <listitem>

	    <para>you checked out with <option>-l</option>, and later

	      change your mind and want to check out the

	      subdirectories as well.</para>

	  </listitem>

	  <listitem>

	    <para>you deleted some subdirectories and want to check

	      them all back out.</para>

	  </listitem>

	</itemizedlist>

	<para><emphasis>Watch the output of the <command>cvs

	      update</command> with care.</emphasis> The letter in

	  front of each filename indicates what was done with

	  it:</para>

	<informaltable frame="none" pgwide="1">

	  <tgroup cols=2>

	    <tbody>

	      <row>

		<entry><literal>U</literal></entry>

		<entry>The file was updated without trouble.</entry>

	      </row>

	      <row>

		<entry><literal>P</literal></entry>

		<entry>The file was updated without trouble (you will

		  only see this when working against a remote

		  repository).</entry>

	      </row>

	      <row>

		<entry><literal>M</literal></entry>

		<entry>The file had been modified, and was merged

		  without conflicts.</entry>

	      </row>

	      <row>

		<entry><literal>C</literal></entry>

		<entry>The file had been modified, and was merged with

		  conflicts.</entry>

	      </row>

	    </tbody>

	  </tgroup>

	</informaltable>

	<para>Merging is what happens if you check out a copy of some

	  file, modify it, then someone else commits a change, and you

	  run <command>cvs update</command>. CVS notices that you have

	  made local changes, and tries to merge your changes with the

	  changes between the version you originally checked out and

	  the one you updated to. If the changes are to separate

	  portions of the file, it will almost always work fine

	  (though the result might not be syntactically or

	  semantically correct).</para>

	<para>CVS will print an <literal>M</literal> in front of every

	  locally modified file even if there is no newer version in

	  the repository, so <command>cvs update</command> is handy

	  for getting a summary of what you have changed

	  locally.</para>

	<para>If you get a <literal>C</literal>, then your changes

	  conflicted with the changes in the repository (the changes

	  were to the same lines, or neighboring lines, or you changed

	  the local file so much that <command>cvs</command> can not

	  figure out how to apply the repository's changes). You will

	  have to go through the file manually and resolve the

	  conflicts; they will be marked with rows of

	  <literal>&lt;</literal>, <literal>=</literal> and

	  <literal>&gt;</literal> signs. For every conflict, there

	  will be a marker line with seven <literal>&lt;</literal>

	  signs and the name of the file, followed by a chunk of what

	  your local file contained, followed by a separator line with

	  seven <literal>=</literal> signs, followed by the

	  corresponding chunk in the repository version, followed by a

	  marker line with seven <literal>&gt;</literal> signs and the

	  revision number you updated to.</para>

      </listitem>

      <listitem>

	<para>View differences between the local version and the

	  repository version with the <command>diff</command>

	  command.</para>

	<screen>&prompt.user; <userinput>cvs diff shazam</userinput></screen>

	<para>shows you every modification you have made to the

	  <filename>shazam</filename> file or module.</para>

	<table frame="none">

	  <title>Useful <command>cvs diff</command> options</title>

	  <tgroup cols=2>

	    <tbody>

	      <row>

		<entry><option>-u</option></entry>

		<entry>Uses the unified diff format.</entry>

	      </row>

	      <row>

		<entry><option>-c</option></entry>

		<entry>Uses the context diff format.</entry>

	      </row>

	      <row>

		<entry><option>-N</option></entry>

		<entry>Shows missing or added files.</entry>

	      </row>

	    </tbody>

	  </tgroup>

	</table>

	<para>You always want to use <option>-u</option>, since

	  unified diffs are much easier to read than almost any other

	  diff format (in some circumstances, context diffs generated

	  with the <option>-c</option> option may be better, but they

	  are much bulkier). A unified diff consists of a series of

	  hunks. Each hunk begins with a line that starts with two

	  <literal>@</literal> signs and specifies where in the file

	  the differences are and how many lines they span. This is

	  followed by a number of lines; some (preceded by a blank)

	  are context; some (preceded by a <literal>-</literal> sign)

	  are outtakes and some (preceded by a <literal>+</literal>)

	  are additions.</para>

	<para>You can also diff against a different version than the

	  one you checked out by specifying a version with

	  <option>-r</option> or <option>-D</option> as in

	  <command>checkout</command> or <command>update</command>, or

	  even view the diffs between two arbitrary versions (without

	  regard for what you have locally) by specifying

	  <emphasis>two</emphasis> versions with <option>-r</option>

	  or <option>-D</option>.</para>

      </listitem>

      <listitem>

	<para>View log entries with the <command>log</command>

	  command.</para>

	<screen>&prompt.user; <userinput>cvs log shazam</userinput></screen>

	<para>If <filename>shazam</filename> is a file, this will

	  print a <emphasis>header</emphasis> with information about

	  this file, such as where in the repository this file is

	  stored, which revision is the <literal>HEAD</literal> for

	  this file, what branches this file is in, and any tags that

	  are valid for this file.  Then, for each revision of this

	  file, a log message is printed.  This includes the date and

	  time of the commit, who did the commit, how many lines were

	  added and/or deleted, and finally the log message that the

	  committer who did the change wrote.</para>

	<para>If <filename>shazam</filename> is a directory, then the

	  log information described above is printed for each file in

	  the directory in turn.  Unless you give the

	  <option>-l</option> to <command>log</command>, the log for

	  all subdirectories of <filename>shazam</filename> is printed

	  too, in a recursive manner.</para>

	<para>Use the <command>log</command> command to view the

	  history of one or more files, as it is stored in the CVS

	  repository.  You can even use it to view the log message of

	  a specific revision, if you add the

	  <option>-r<replaceable>rev</replaceable></option> to the

	  <command>log</command> command:</para>

	<screen>&prompt.user; <userinput>cvs log -r1.2 shazam</userinput></screen>

	<para>This will print only the log message for revision

	  <literal>1.2</literal> of file <filename>shazam</filename>

	  if it is a file, or the log message for revision

	  <literal>1.2</literal> of each file under

	  <filename>shazam</filename> if it is a directory.</para>

      </listitem>

      <listitem>

	<para>See who did what with the <command>annotate</command>

	  command.  This command shows you each line of the specified

	  file or files, along with which user most recently changed

	  that line.</para>

	<screen>&prompt.user; <userinput>cvs annotate shazam</userinput></screen>

      </listitem>

      <listitem>

	<para>Add new files with the <command>add</command>

	  command.</para>

	<para>Create the file, <command>cvs add</command> it, then

	  <command>cvs commit</command> it.</para>

	<para>Similarly, you can add new directories by creating them

	  and then <command>cvs add</command>ing them. Note that you

	  do not need to commit directories.</para>

      </listitem>

      <listitem>

	<para>Remove obsolete files with the <command>remove</command>

	  command.</para>

	<para>Remove the file, then <command>cvs rm</command> it, then

	  <command>cvs commit</command> it.</para>

      </listitem>

      <listitem>

	<para>Commit with the <command>commit</command> or

	  <command>checkin</command> command.</para>

	<table frame="none">

	  <title>Useful <command>cvs commit</command> options</title>

	  <tgroup cols=2>

	    <tbody>

	      <row>

		<entry><option>-f</option></entry>

		<entry>Force a commit of an unmodified file.</entry>

	      </row>

	      <row>

		<entry><option>-m<replaceable>msg</replaceable></option></entry>

		<entry>Specify a commit message on the command line

		  rather than invoking an editor.</entry>

	      </row>

	    </tbody>

	  </tgroup>

	</table>

	<para>The following are some Subversion examples related to

	  the src repository.  More (in-depth) information can be

	  found in the Subversion Primer at <xref

	    linkend="subversion-primer"> and <ulink

	     url="http://wiki.freebsd.org/SubversionMissing">List of

	   things missing in Subversion when compared to CVS</ulink>.

	  The notes at <ulink

	    url="http://people.freebsd.org/~peter/svn_notes.txt"></ulink>

	  might also be useful.  Subversion is also described in-depth

	  in <ulink url="http://svnbook-red-bean.com/">Version Control

	    with Subversion</ulink>.</para>

	<itemizedlist>

	  <listitem>

	    <para>Check out the <literal>head</literal> branch:</para>

	    <screen>&prompt.user; <userinput>svn co svn+ssh://svn.freebsd.org/base/head /usr/src</userinput></screen>

	  </listitem>

	</itemizedlist>

	<para>Good commit messages are important. They tell others why

	  you did the changes you did, not just right here and now,

	  but months or years from now when someone wonders why some

	  seemingly illogical or inefficient piece of code sneaked

	  into your source file. It is also an invaluable aid to

	  deciding which changes to MFC and which not to MFC.</para>

	<para>Commit messages should be clear, concise and provide

	  a reasonable summary to give an indication of what was

	  changed and why.</para>

	<para>Commit messages should provide enough information to

	  enable a third party to decide if the change is relevant to

	  them and if they need to read the change itself.</para>

	<para>Avoid committing several unrelated changes in one go. It

	  makes merging difficult, and also makes it harder to

	  determine which change is the culprit if a bug crops

	  up.</para>

	<para>Avoid committing style or whitespace fixes and

	  functionality fixes in one go. It makes merging difficult,

	  and also makes it harder to understand just what functional

	  changes were made.  In the case of documentation files, it

	  can make the job of the translation teams more complicated,

	  as it becomes difficult for them to determine exactly what

	  content changes need to be translated.</para>

	<para>Avoid committing changes to multiple files in one go

	  with a generic, vague message. Instead, commit each file (or

	  small, related groups of files) with tailored commit

	  messages.</para>

	<para>Before committing, <emphasis>always</emphasis>:</para>

	<itemizedlist>

	  <listitem>

	    <para>verify which branch you are committing to, using

	      <command>svn status</command>.  This is only needed for

	      the src tree, as the other trees are not branched.</para>

	  </listitem>

	  <listitem>

	    <para>review your diffs, using the diff command of the

	      version control system.</para>

	  </listitem>

	</itemizedlist>

	<para>Also, ALWAYS specify which files to commit explicitly on

	  the command line, so you do not accidentally commit other

	  files than the ones you intended — a commit operation

	  without any arguments usually will commit every modification

	  in your current working directory and every

	  subdirectory.</para>

      </listitem>

    </orderedlist>

    <para>Additional tips and tricks:</para>

    <orderedlist>

      <listitem>

	<para>You can place commonly used options in your

	  <filename>~/.cvsrc</filename>, like this:</para>

	<programlisting>cvs -z3

diff -Nu

update -Pd

checkout -P</programlisting>

	<para>This example says:</para>

	<itemizedlist>

	  <listitem>

	    <para>always use compression level 3 when talking to a

	      remote server. This is a life-saver when working over a

	      slow connection.</para>

	  </listitem>

	  <listitem>

	    <para>always use the <option>-N</option> (show added or

	      removed files) and <option>-u</option> (unified diff

	      format) options to &man.diff.1;.</para>

	  </listitem>

	  <listitem>

	    <para>always use the <option>-P</option> (prune empty

	      directories) and <option>-d</option> (check out new

	      directories) options when updating.</para>

	  </listitem>

	  <listitem>

	    <para>always use the <option>-P</option> (prune empty

	      directories) option when checking out.</para>

	  </listitem>

	</itemizedlist>

      </listitem>

      <listitem>

	<para>Use Eivind Eklund's <command>cdiff</command> script to

	  view unidiffs.  It is a wrapper for &man.less.1; that adds

	  ANSI color codes to make hunk headers, outtakes and

	  additions stand out; context and garbage are unmodified.  It

	  also expands tabs properly (tabs often look wrong in diffs

	  because of the extra character in front of each

	  line).</para>

	<para><filename

	    role="package">textproc/cdiff</filename></para>

	<para>Simply use it instead of &man.more.1; or

	  &man.less.1;:</para>

	<screen>&prompt.user; <userinput>cvs diff -Nu shazam | cdiff</userinput></screen>

	<para>Alternatively some editors like &man.vim.1; (<filename

	    role="package">editors/vim</filename>) have color support

	  and when used as a pager with color syntax highlighting

	  switched on will highlight many types of file, including

	  diffs, patches, and CVS/RCS logs.</para>

	<screen>&prompt.user; <userinput>echo "syn on" &gt;&gt; ~/.vimrc </userinput>

&prompt.user; <userinput>cvs diff -Nu shazam | vim -</userinput>

&prompt.user; <userinput>cvs log shazam | vim -</userinput> </screen>

      </listitem>

      <listitem>

	<para>CVS is old, arcane, crufty and buggy, and sometimes

	  exhibits non-deterministic behavior which some claim as

	  proof that it is actually merely the Newtonian manifestation

	  of a sentient transdimensional entity.  It is not humanly

	  possible to know its every quirk inside out, so do not be

	  afraid to ask the resident AI (&a.cvsadm;) for help.</para>

      </listitem>

      <listitem>

	<para>Do not leave the <command>cvs commit</command> command

	  in commit message editing mode for too long (more than

	  2–3 minutes).  It locks the directory you are working

	  with and will prevent other developers from committing into

	  the same directory.  If you have to type a long commit

	  message, type it before executing <command>cvs

	    commit</command> and insert it into the commit message or

	  save it in a file before committing and use the

	  <option>-F</option> option of CVS to read the commit message

	  from that file, i.e.,</para>

	  <screen>&prompt.user; <userinput>vi logmsg</userinput>

&prompt.user; <userinput>cvs ci -F logmsg shazam</userinput></screen>

	<para>This is the fastest way of passing a commit message to

	  CVS but you should be careful when editing the

	  <filename>logmsg</filename> file before the commit, because

	  CVS will not give you a chance to edit the message when you

	  do the actual commit.</para>

      </listitem>

      <listitem>

	<para>Speed up your CVS operation considerably by using a

	  persistent ssh connection to the repository machine.  First,

	  put this configuration into your

	  <filename>~/.ssh/config</filename>:</para>

	<programlisting>Host pcvs.FreeBSD.org

      ControlPath /home/<replaceable>user</replaceable>/.ssh/cvs.cpath

Host projcvs.FreeBSD.org

      ControlPath /home/<replaceable>user</replaceable>/.ssh/cvs.cpath</programlisting>

	<para>Now open the persistent connection to the

	  repoman:</para>

	<screen>&prompt.user; <userinput>ssh -fNM ncvs.FreeBSD.org</userinput></screen>

	<para>The CVS commands should now respond faster, as they are

	  reusing existing connection with the repository.  Note that

	  all the hostnames are case sensitive.</para>

      </listitem>

    </orderedlist>

  </sect1>

  <sect1 id="subversion-primer">

    <title>Subversion Primer</title>

	        <para>In the proper directory:

<command>cvs update -D <replaceable>datespec</replaceable></command>.</para>

              </step>

              <step>

	    <para>When do we <emphasis>not</emphasis> need a

	      repository copy?</para>

	  </question>

	  <answer>

	    <para>When there is no history to preserve.  If a port is

	      added into a wrong category and is moved immediately,

	      it suffices to simply <command>cvs remove</command> the

	      old one and <command>addport</command> the new

	      one.</para>

	  </answer>

	</qandaentry>

	<qandaentry>

	  <question>