Date: Wed, 30 May 2012 00:05:46 +0000 (UTC) From: Glen Barber <gjb@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r38937 - head/en_US.ISO8859-1/articles/committers-guide Message-ID: <201205300005.q4U05ksZ012185@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201205300005.q4U05ksZ012185>