svn commit: r38937 - head/en_US.ISO8859-1/articles/committers-guide
Glen Barber
gjb at FreeBSD.org
Wed May 30 00:05:47 UTC 2012
Author: gjb
Date: Wed May 30 00:05:46 2012
New Revision: 38937
URL: http://svn.freebsd.org/changeset/doc/38937
Log:
Whitespace cleanup:
- Wrap long lines
- Remove trailing/leading whitespace
- Clean up superfluous empty lines
Translators, please ignore.
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 Tue May 29 21:21:50 2012 (r38936)
+++ head/en_US.ISO8859-1/articles/committers-guide/article.sgml Wed May 30 00:05:46 2012 (r38937)
@@ -40,19 +40,21 @@
</legalnotice>
<abstract>
- <para>This document provides information for the FreeBSD committer
- community. All new committers should read this document before they
- start, and existing committers are strongly encouraged to review it
- from time to time.</para>
+ <para>This document provides information for the FreeBSD
+ committer community. All new committers should read this
+ document before they start, and existing committers are
+ strongly encouraged to review it from time to time.</para>
<para>Almost all FreeBSD developers have commit rights to one or
- more repositories. However, a few developers do not, and some of
- the information here applies to them as well. (For instance, some
- people only have rights to work with the Problem Report database).
- Please see <xref linkend="non-committers"> for more information.</para>
-
- <para>This document may also be of interest to members of the FreeBSD
- community who want to learn more about how the project works.</para>
+ more repositories. However, a few developers do not, and some
+ of the information here applies to them as well. (For
+ instance, some people only have rights to work with the
+ Problem Report database). Please see <xref
+ linkend="non-committers"> for more information.</para>
+
+ <para>This document may also be of interest to members of the
+ FreeBSD community who want to learn more about how the project
+ works.</para>
</abstract>
</articleinfo>
@@ -71,14 +73,17 @@
<row>
<entry><emphasis>Main Shell Host</emphasis></entry>
- <entry><hostid role="fqdn">freefall.FreeBSD.org</hostid></entry>
+ <entry><hostid
+ role="fqdn">freefall.FreeBSD.org</hostid></entry>
</row>
<row>
- <entry><emphasis><literal>src/</literal> Subversion Root</emphasis></entry>
+ <entry><emphasis><literal>src/</literal> Subversion
+ Root</emphasis></entry>
<entry>
- <literal>svn+ssh://</literal><hostid role="fqdn">svn.FreeBSD.org</hostid><filename>/base</filename> (see also <xref linkend="subversion-primer">).
- </entry>
+ <literal>svn+ssh://</literal><hostid
+ role="fqdn">svn.FreeBSD.org</hostid><filename>/base</filename>
+ (see also <xref linkend="subversion-primer">).</entry>
</row>
<row>
<entry><emphasis><literal>doc/</literal> Subversion
@@ -86,18 +91,15 @@
<entry>
<literal>svn+ssh://</literal><hostid
role="fqdn">svn.FreeBSD.org</hostid><filename>/doc</filename>
- (see also <xref linkend="subversion-primer">).
- </entry>
+ (see also <xref linkend="subversion-primer">).</entry>
</row>
<row>
<entry><emphasis><literal>ports/</literal> CVS Root</emphasis></entry>
<entry>
-
- <hostid role="fqdn">pcvs.FreeBSD.org</hostid><literal>:</literal><filename>/home/pcvs</filename>
- (see also <xref linkend="vcs.operations">).
-
- </entry>
+ <hostid
+ role="fqdn">pcvs.FreeBSD.org</hostid><literal>:</literal><filename>/home/pcvs</filename>
+ (see also <xref linkend="vcs.operations">).</entry>
</row>
<row>
@@ -105,23 +107,24 @@
<entry>developers (technically called all-developers),
doc-developers, doc-committers, ports-developers,
- ports-committers, src-developers, src-committers.
- (Each project
- repository has its own -developers and -committers mailing
- lists. Archives for these lists may be found in files
- <filename>/home/mail/<replaceable>repository-name</replaceable>-developers-archive</filename>
- and
- <filename>/home/mail/<replaceable>repository-name</replaceable>-committers-archive</filename>
- on the <hostid role="domainname">FreeBSD.org</hostid>
- cluster.)
- </entry>
+ ports-committers, src-developers, src-committers. (Each
+ project repository has its own -developers and
+ -committers mailing lists. Archives for these lists may
+ be found in files
+ <filename>/home/mail/<replaceable>repository-name</replaceable>-developers-archive</filename>
+ and
+ <filename>/home/mail/<replaceable>repository-name</replaceable>-committers-archive</filename>
+ on the <hostid role="domainname">FreeBSD.org</hostid>
+ cluster.)</entry>
</row>
<row>
- <entry><emphasis>Core Team monthly reports</emphasis></entry>
+ <entry><emphasis>Core Team monthly
+ reports</emphasis></entry>
<entry><filename>/home/core/public/monthly-reports</filename>
- on the <hostid role="domainname">FreeBSD.org</hostid> cluster.
+ on the <hostid role="domainname">FreeBSD.org</hostid>
+ cluster.
</entry>
</row>
@@ -129,8 +132,8 @@
<entry><emphasis>Ports Management Team monthly
reports</emphasis></entry>
<entry><filename>/home/portmgr/public/monthly-reports</filename>
- on the <hostid role="domainname">FreeBSD.org</hostid> cluster.
- </entry>
+ on the <hostid role="domainname">FreeBSD.org</hostid>
+ cluster.</entry>
</row>
<row>
@@ -160,11 +163,13 @@
<listitem><para><ulink url="&url.base;/internal/">FreeBSD
Project Internal Pages</ulink></para></listitem>
- <listitem><para><ulink url="&url.base;/internal/machines.html">FreeBSD
- Project Hosts</ulink></para></listitem>
-
- <listitem><para><ulink url="&url.base;/administration.html">FreeBSD
- Project Administrative Groups</ulink></para></listitem>
+ <listitem><para><ulink
+ url="&url.base;/internal/machines.html">FreeBSD Project
+ Hosts</ulink></para></listitem>
+
+ <listitem><para><ulink
+ url="&url.base;/administration.html">FreeBSD Project
+ Administrative Groups</ulink></para></listitem>
</itemizedlist>
</sect1>
@@ -176,13 +181,13 @@
documentation, third party application ports infrastructure, and
various maintained utilities. When FreeBSD commit bits are
allocated, the areas of the tree where the bit may be used are
- specified. Generally, the areas associated with a bit reflect who
- authorized the allocation of the commit bit. Additional areas of
- authority may be added at a later date: when this occurs, the
- committer should follow normal commit bit allocation procedures for
- that area of the tree, seeking approval from the appropriate entity
- and possibly getting a mentor for that area for some period of time.
- </para>
+ specified. Generally, the areas associated with a bit reflect
+ who authorized the allocation of the commit bit. Additional
+ areas of authority may be added at a later date: when this
+ occurs, the committer should follow normal commit bit allocation
+ procedures for that area of the tree, seeking approval from the
+ appropriate entity and possibly getting a mentor for that area
+ for some period of time.</para>
<informaltable frame="none" pgwide="1">
<tgroup cols="3">
@@ -214,19 +219,19 @@
</tgroup>
</informaltable>
- <para>Commit bits allocated prior to the development of the notion of
- areas of authority may be appropriate for use in many parts of the
- tree. However, common sense dictates that a committer who has not
- previously worked in an area of the tree seek review prior to
- committing, seek approval from the appropriate responsible party,
- and/or work with a mentor. Since the rules regarding code
- maintenance differ by area of the tree, this is as much for the
- benefit of the committer working in an area of less familiarity as
- it is for others working on the tree.</para>
-
- <para>Committers are encouraged to seek review for their work as part
- of the normal development process, regardless of the area of the
- tree where the work is occurring.</para>
+ <para>Commit bits allocated prior to the development of the notion
+ of areas of authority may be appropriate for use in many parts
+ of the tree. However, common sense dictates that a committer
+ who has not previously worked in an area of the tree seek review
+ prior to committing, seek approval from the appropriate
+ responsible party, and/or work with a mentor. Since the rules
+ regarding code maintenance differ by area of the tree, this is
+ as much for the benefit of the committer working in an area of
+ less familiarity as it is for others working on the tree.</para>
+
+ <para>Committers are encouraged to seek review for their work as
+ part of the normal development process, regardless of the area
+ of the tree where the work is occurring.</para>
<sect2>
<title>Policy for <filename>doc/</filename> committer activity
@@ -250,7 +255,7 @@
will involve a continuing of <quote>Approved by</quote> for
some period.</para></listitem>
- <listitem><para>"Approved by" is only acceptable from
+ <listitem><para>"Approved by" is only acceptable from
non-mentored src committers -- mentored committers can
provide a "Reviewed by" but not an "Approved
by".</para></listitem>
@@ -262,65 +267,69 @@
<sect1 id="vcs.operations">
<title>Version Control System Operations</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
+ <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
+ <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>
-
+ <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
+ <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.
+ <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>
+ 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>
@@ -351,62 +360,64 @@
</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
+ <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.
+ <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
+ <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>
+ 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
+ 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>
+ 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>
+ <para>&a.des; also supplied the following <quote>mini
+ primer</quote> for CVS.</para>
<orderedlist>
<listitem>
@@ -415,12 +426,15 @@ alias projcvs cvs -d <replaceable>user</
<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>
+ <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>
+ <title>Useful <command>cvs checkout</command>
+ options</title>
<tgroup cols=2>
<tbody>
@@ -431,7 +445,8 @@ alias projcvs cvs -d <replaceable>user</
<row>
<entry><option>-l</option></entry>
- <entry>Check out a single level, no subdirectories</entry>
+ <entry>Check out a single level, no
+ subdirectories</entry>
</row>
<row>
@@ -454,12 +469,14 @@ alias projcvs cvs -d <replaceable>user</
<itemizedlist>
<listitem>
<para>Check out the <filename>Tools</filename> module,
- which corresponds to <filename>ports/Tools</filename>:</para>
+ 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>,
+ <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>
@@ -467,39 +484,42 @@ alias projcvs cvs -d <replaceable>user</
<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
+ <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>
+ <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>
+ <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>
-
+ 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>
+ <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>
+ <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>
@@ -507,8 +527,8 @@ alias projcvs cvs -d <replaceable>user</
</listitem>
<listitem>
- <para>Check out the <filename>Tools</filename> module as it was
- one week ago:</para>
+ <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>
@@ -517,8 +537,8 @@ alias projcvs cvs -d <replaceable>user</
</itemizedlist>
<para>Note that cvs stores metadata in subdirectories named
- <filename>CVS</filename>.
- Similarly, Subversion 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>
@@ -532,8 +552,8 @@ alias projcvs cvs -d <replaceable>user</
<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
+ <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>
@@ -547,8 +567,8 @@ alias projcvs cvs -d <replaceable>user</
<row>
<entry>Needs Patch</entry>
- <entry>File is unmodified, but there is a newer revision in
- the repository.</entry>
+ <entry>File is unmodified, but there is a newer
+ revision in the repository.</entry>
</row>
<row>
@@ -558,14 +578,15 @@ alias projcvs cvs -d <replaceable>user</
<row>
<entry>Needs Merge</entry>
- <entry>File is modified, and there is a newer revision in the
- repository.</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>
+ <entry>There were conflicts the last time this file
+ was updated, and they have not been resolved
+ yet.</entry>
</row>
</tbody>
</tgroup>
@@ -579,8 +600,8 @@ alias projcvs cvs -d <replaceable>user</
</listitem>
<listitem>
- <para>Once you have checked something out, you can update it with the
- <command>update</command> command.</para>
+ <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>
@@ -588,8 +609,8 @@ alias projcvs cvs -d <replaceable>user</
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>
+ 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>
@@ -599,7 +620,8 @@ alias projcvs cvs -d <replaceable>user</
<tbody>
<row>
<entry><option>-d</option></entry>
- <entry>Check out any additional missing directories.</entry>
+ <entry>Check out any additional missing
+ directories.</entry>
</row>
<row>
@@ -613,14 +635,16 @@ alias projcvs cvs -d <replaceable>user</
<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>
+ 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>
+ 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>
@@ -632,8 +656,8 @@ alias projcvs cvs -d <replaceable>user</
<listitem>
<para>you checked out with <option>-l</option>, and later
- change your mind and want to check out the subdirectories
- as well.</para>
+ change your mind and want to check out the
+ subdirectories as well.</para>
</listitem>
<listitem>
@@ -643,8 +667,9 @@ alias projcvs cvs -d <replaceable>user</
</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>
+ 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>
@@ -656,14 +681,15 @@ alias projcvs cvs -d <replaceable>user</
<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>
+ <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>
+ <entry>The file had been modified, and was merged
+ without conflicts.</entry>
</row>
<row>
@@ -675,37 +701,38 @@ alias projcvs cvs -d <replaceable>user</
</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>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>
+ 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>
@@ -743,25 +770,25 @@ alias projcvs cvs -d <replaceable>user</
<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)
+ 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>
+ 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>
+ <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>
@@ -770,49 +797,52 @@ alias projcvs cvs -d <replaceable>user</
<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
+ <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
+ <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>
+ <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>
+ <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>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>
@@ -823,7 +853,8 @@ alias projcvs cvs -d <replaceable>user</
</listitem>
<listitem>
- <para>Remove obsolete files with the <command>remove</command> command.</para>
+ <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>
@@ -845,23 +876,24 @@ alias projcvs cvs -d <replaceable>user</
<row>
<entry><option>-m<replaceable>msg</replaceable></option></entry>
- <entry>Specify a commit message on the command line rather
- than invoking an editor.</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>.
+ <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>
+ 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>
+ in <ulink url="http://svnbook-red-bean.com/">Version Control
+ with Subversion</ulink>.</para>
<itemizedlist>
<listitem>
@@ -871,12 +903,12 @@ alias projcvs cvs -d <replaceable>user</
</listitem>
</itemizedlist>
- <para>Good commit messages are important. They tell others
- why you did the changes you did, not just right here and now,
+ <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>
+ 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
@@ -887,8 +919,9 @@ alias projcvs cvs -d <replaceable>user</
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>
+ 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,
@@ -900,7 +933,8 @@ alias projcvs cvs -d <replaceable>user</
<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>
+ small, related groups of files) with tailored commit
+ messages.</para>
<para>Before committing, <emphasis>always</emphasis>:</para>
@@ -912,15 +946,17 @@ alias projcvs cvs -d <replaceable>user</
</listitem>
<listitem>
- <para>review your diffs, using the diff command of the version control system.</para>
+ <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>
+ 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>
@@ -967,23 +1003,26 @@ checkout -P</programlisting>
<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>
+ view unidiffs. It is a wrapper for &man.less.1; that adds
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-doc-all
mailing list