svn commit: r39217 - head/en_US.ISO8859-1/articles/committers-guide
Beat Gaetzi
beat at FreeBSD.org
Sun Jul 15 19:31:38 UTC 2012
Author: beat (ports committer)
Date: Sun Jul 15 19:31:37 2012
New Revision: 39217
URL: http://svn.freebsd.org/changeset/doc/39217
Log:
- Remove CVS chapter as ports has switched to Subversion too
- Add ports specific information to the Subversion primer
PR: docs/169772
Submitted by: myself, modified by gjb
Approved by: gjb
Modified:
head/en_US.ISO8859-1/articles/committers-guide/article.sgml
Modified: head/en_US.ISO8859-1/articles/committers-guide/article.sgml
==============================================================================
--- head/en_US.ISO8859-1/articles/committers-guide/article.sgml Sun Jul 15 19:27:17 2012 (r39216)
+++ head/en_US.ISO8859-1/articles/committers-guide/article.sgml Sun Jul 15 19:31:37 2012 (r39217)
@@ -95,11 +95,12 @@
</row>
<row>
- <entry><emphasis><literal>ports/</literal> CVS Root</emphasis></entry>
+ <entry><emphasis><literal>ports/</literal> Subversion
+ Root</emphasis></entry>
<entry>
- <hostid
- role="fqdn">pcvs.FreeBSD.org</hostid><literal>:</literal><filename>/home/pcvs</filename>
- (see also <xref linkend="vcs.operations">).</entry>
+ <literal>svn+ssh://</literal><hostid
+ role="fqdn">svn.FreeBSD.org</hostid><filename>/ports</filename>
+ (see also <xref linkend="subversion-primer">).</entry>
</row>
<row>
@@ -264,827 +265,21 @@
</sect1>
- <sect1 id="vcs.operations">
- <title>Version Control System Operations</title>
+ <sect1 id="subversion-primer">
+ <title>Subversion Primer</title>
<para>It is assumed that you are already familiar with the basic
operation of the version control systems in use. Traditionally
this was CVS. Subversion is used for the <literal>src</literal>
- tree as of May 2008 and the <literal>doc/www</literal> tree as
- of May 2012. Subversion is covered in <xref
- linkend="subversion-primer">.</para>
-
- <para>The &a.cvsadm; are the <quote>owners</quote> of the
- repository and are responsible for direct modification of it for
- the purposes of cleanup or fixing some unfortunate abuse of the
- version control system by a committer. Should you cause some
- repository accident, say a bad import or a bad tag creation,
- mail the responsible part of &a.cvsadm;, as stated in the table
- below, (or call one of them) and report the problem. For very
- important issues affecting the entire tree—not just a
- specific area—you can contact the &a.cvsadm;. Please do
- <emphasis>not</emphasis> contact the &a.cvsadm; for repocopies
- or other things that the more specific teams can handle.</para>
-
- <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><</literal>, <literal>=</literal> and
- <literal>></literal> signs. For every conflict, there
- will be a marker line with seven <literal><</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>></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" >> ~/.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>
+ tree as of May 2008, the <literal>doc/www</literal> tree as of
+ May 2012 and the <literal>ports</literal> tree as of July 2012.
+ </para>
- <sect1 id="subversion-primer">
- <title>Subversion Primer</title>
+ <para><ulink url="http://wiki.freebsd.org/SubversionMissing">There
+ is a 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.</para>
<sect2 id="svn-intro">
<title>Introduction</title>
@@ -1110,6 +305,11 @@ Host projcvs.FreeBSD.org
<literal>head/<replaceable>lang</replaceable>/htdocs/</literal>.</para>
</note>
+ <para>The &os; <literal>ports</literal> repository switched
+ from <acronym>CVS</acronym> to Subversion on July 14th, 2012.
+ The first real <acronym>SVN</acronym> commit is
+ <emphasis>r300894</emphasis>.</para>
+
<para>There are mechanisms in place to automatically merge
changes back from the Subversion repository to the
<acronym>CVS</acronym> one, so regular users should not notice
@@ -1182,12 +382,19 @@ Host projcvs.FreeBSD.org
<screen>&prompt.user; <userinput>svn checkout svn+ssh://svn.freebsd.org/doc/head /usr/doc</userinput></screen>
+ <para>For the <literal>ports</literal> tree, use:</para>
+
+ <screen>&prompt.user; <userinput>svn checkout svn+ssh://svn.freebsd.org/ports/head /usr/ports</userinput></screen>
+
<note>
<para>Though the remaining examples in this document are
written with the workflow of working with the
<literal>src</literal> tree in mind, the underlying
concepts are the same for working with the
- <literal>doc</literal> tree.</para>
+ <literal>doc</literal> and the <literal>ports</literal>
+ tree.
+ Ports related Subversion operations are listed in
+ <xref linkend="ports">.</para>
</note>
<para>The above command will check out a
@@ -1456,6 +663,39 @@ Host projcvs.FreeBSD.org
</listitem>
</itemizedlist>
</sect3>
+
+ <sect3>
+ <title>&os; Ports Tree Branches and Layout</title>
+
+ <para>In <literal>svn+ssh://svn.freebsd.org/ports</literal>,
+ <emphasis>ports</emphasis> refers repository root of the
+ ports tree.</para>
+
+ <para>In general, most &os; port work will be done within
+ the <filename>head/</filename> branch of the ports tree
+ which is the actual ports tree used to install software.
+ Some other key locations are:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>/branches/RELENG_<replaceable>n_n_n
+ </replaceable></emphasis> which corresponds to
+ <literal>RELENG_<replaceable>n_n_n</replaceable></literal>
+ is used to merge back security updates in preparation
+ for a release.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>/tags/RELEASE_<replaceable>n_n_n</replaceable></emphasis>
+ which corresponds to <literal>RELEASE_<replaceable>n_n_n</replaceable></literal>
+ represents a release tag of the ports tree.</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>/tags/RELEASE_<replaceable>n</replaceable>_EOL</emphasis>
+ represents the end of life tag of a specific &os;
+ branch.</para>
+ </listitem>
+ </itemizedlist>
+ </sect3>
</sect2>
<sect2 id="svn-daily-use">
@@ -1609,6 +849,13 @@ Host projcvs.FreeBSD.org
in a single operation:</para>
<screen>&prompt.user; <userinput>svn commit <replaceable>lib/libfetch</replaceable> <replaceable>usr/bin/fetch</replaceable></userinput></screen>
+
+ <para>There is also a commit wrapper for the ports tree
+ to handle the properties and sanity checking your
+ changes:</para>
+
+ <screen>&prompt.user; <userinput>/usr/ports/Tools/scripts/psvn commit
+ </userinput></screen>
</sect3>
<sect3 id="subversion-primer-add-remove">
@@ -1617,6 +864,9 @@ Host projcvs.FreeBSD.org
<note>
<para>Before adding files, get a copy of <ulink
url="http://people.freebsd.org/~peter/auto-props.txt">auto-props.txt</ulink>
+ (there is also a <ulink
+ url="http://people.freebsd.org/~beat/cvs2svn/auto-props.txt">
+ ports tree specific version</ulink>)
and add it to <filename>~/.subversion/config</filename>
according to the instructions in the file. If you added
something before you've read this, you may use
@@ -1624,7 +874,8 @@ Host projcvs.FreeBSD.org
files, fix your config file and re-add them again. The
initial config file is created when you first run a svn
command, even something as simple as <command>svn
- help</command>.</para>
+ help</command>.
+ </para>
</note>
<para>As with <acronym>CVS</acronym>, files are added to a
@@ -2724,6 +1975,9 @@ $target - head/$source:$P,$Q,$R</screen>
<para>In commit logs etc., <quote>rev 179872</quote> should be
spelled <quote>r179872</quote> as per convention.</para>
+ <para>Don't remove and re-add the same file in a single commit
+ as this will break the CVS exporter.</para>
+
<para>Speeding up checkouts and minimising network traffic is
possible with the following recipe:</para>
@@ -4287,7 +3541,7 @@ $target - head/$source:$P,$Q,$R</screen>
<procedure>
<step>
- <para>Remove the port's files via <command>cvs remove</command>.</para>
+ <para>Remove the port's files via <command>svn remove</command>.</para>
</step>
<step>
@@ -4329,20 +3583,20 @@ $target - head/$source:$P,$Q,$R</screen>
<para>This is essentially the reverse of deleting a port.</para>
<procedure>
<step>
- <para>Figure out when the port was removed. Use the ports
- <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/">cvsweb</ulink>
- and then navigate to
- <replaceable>category</replaceable>/<replaceable>portname</replaceable>/<filename>Attic</filename>/ .
+ <para>Figure out when the port was removed. Use this
+ <ulink url="http://people.freebsd.org/~crees/removed_ports/index.xml">list</ulink>
+ and then copy the last living revision of the port:
+
+ <screen>&prompt.user; <userinput>cd /usr/ports/<replaceable>category
+ </replaceable></userinput>
+&prompt.user; <userinput>svn cp 'svn+ssh://svn.freebsd.org/ports/<replaceable>category</replaceable>/<replaceable>portname</replaceable>/@{<replaceable>YYYY-MM-DD</replaceable>}' <replaceable>portname</replaceable>
+ </userinput></screen>
+
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-doc-all
mailing list