Date: Sun, 15 Jul 2012 19:31:38 +0000 (UTC) From: Beat Gaetzi <beat@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r39217 - head/en_US.ISO8859-1/articles/committers-guide Message-ID: <201207151931.q6FJVcMm067877@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201207151931.q6FJVcMm067877>