aboutsummaryrefslogtreecommitdiffstats
path: root/doc/user
diff options
context:
space:
mode:
authorPeter Wemm <peter@FreeBSD.org>2013-06-18 02:07:41 +0000
committerPeter Wemm <peter@FreeBSD.org>2013-06-18 02:07:41 +0000
commit32547653cc5376642e1231fb644db99933ac8db4 (patch)
tree135691142dc0e75a5e5d97b5074d03436435b8e0 /doc/user
downloadsrc-32547653cc5376642e1231fb644db99933ac8db4.tar.gz
src-32547653cc5376642e1231fb644db99933ac8db4.zip
Import trimmed svn-1.8.0-rc3vendor/subversion/subversion-1.8.0-rc3
Notes
Notes: svn path=/vendor/subversion/dist/; revision=251881 svn path=/vendor/subversion/subversion-1.8.0-rc3/; revision=251882; tag=vendor/subversion/subversion-1.8.0-rc3
Diffstat (limited to 'doc/user')
-rw-r--r--doc/user/cvs-crossover-guide.html906
-rw-r--r--doc/user/lj_article.txt323
-rw-r--r--doc/user/svn-best-practices.html350
3 files changed, 1579 insertions, 0 deletions
diff --git a/doc/user/cvs-crossover-guide.html b/doc/user/cvs-crossover-guide.html
new file mode 100644
index 000000000000..d038a3999efa
--- /dev/null
+++ b/doc/user/cvs-crossover-guide.html
@@ -0,0 +1,906 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
+<title>CVS to SVN Crossover Guide</title>
+<style type="text/css">
+body {
+ font-family: sans-serif;
+}
+h1 {
+ text-align: center;
+}
+h2 {
+ background: #b0c0f0;
+ margin: 0;
+}
+.h2 {
+ border-left: 4px #b0c0f0 solid;
+ margin-bottom: 2em;
+}
+hr {
+ height: 1px;
+ width: 80%;
+}
+p, h3, dl {
+ padding-left: 1em;
+}
+dd {
+ margin-left: 2em;
+}
+.sidebyside {
+ padding: 0 2em;
+ width: 100%;
+ font-size: 80%;
+}
+.sidebyside th, .sidebyside td {
+ width: 50%;
+ border-width: 0 1px 2px 0;
+ border-style: solid;
+ border-color: black;
+ background: #b0c0f0;
+ vertical-align: top;
+}
+.sidebyside th {
+ text-align: center;
+ background: #90a0d0;
+}
+.bookref {
+ font-size: 80%;
+}
+</style>
+</head>
+
+<body>
+
+<h1>CVS to SVN Crossover Guide</h1>
+
+<!-- ==================================================================== -->
+<div class="h2">
+<h2>Purpose</h2>
+
+<p>This document provides an alternate method of learning Subversion.
+ Many users dislike learning new technology via a theoretical "top
+ down" approach, as provided by the <a
+ href="http://svnbook.red-bean.com">Subversion Book</a>. Instead,
+ this document presents Subversion from the "bottom up": it shows a
+ CVS command or task, and then shows the equivalent task in
+ Subversion (along with relevant book links.) It's essentially a
+ re-indexing of topics covered by the book, keyed on CVS tasks.</p>
+
+</div>
+
+<!-- ==================================================================== -->
+<div class="h2">
+<h2>Table of Contents</h2>
+
+<h3>Setup</h3>
+<ul>
+ <li><a href="#repos_creation">Repository creation</a></li>
+ <li><a href="#import">Importing data</a></li>
+ <li><a href="#installing">Installing a server</a></li>
+ <li><a href="#authenticating">Authenticating to a server</a></li>
+ <li><a href="#browsing">Browsing a repository</a></li>
+ <li><a href="#checkingout">Checking out a working copy</a></li>
+</ul>
+
+<h3>Basic Work Cycle</h3>
+<ul>
+ <li><a href="#changeditems">Seeing locally changed items</a></li>
+ <li><a href="#outofdate">Seeing out-of-date items</a></li>
+ <li><a href="#scheduling">Scheduling additions or deletions</a></li>
+ <li><a href="#copying">Copying and moving</a></li>
+ <li>Undoing local changes</li>
+ <li>Updating and committing</li>
+ <li>Resolving conflicts</li>
+ <li>Adding a binary file</li>
+ <li>Using native line-endings</li>
+</ul>
+
+<h3>Examining history</h3>
+<ul>
+ <li>Seeing history of an item</li>
+ <li>Comparing two versions of an item</li>
+</ul>
+
+<h3>Branching/Tagging/Merging</h3>
+<ul>
+ <li>Creating a branch</li>
+ <li>Moving a working copy to a branch</li>
+ <li>Finding the beginning of a branch</li>
+ <li>Porting a single change</li>
+ <li>Merging a whole branch</li>
+ <li>Reverting a committed change</li>
+ <li>Resurrecting deleted items</li>
+ <li>Creating a tag</li>
+ <li>Tweaking a tag</li>
+ <li>Seeing all tags</li>
+ <li>Comparing two tags</li>
+ <li>Seeing logs between two tags</li>
+</ul>
+
+<h3>Other tasks</h3>
+<ul>
+ <li>Using modules</li>
+ <li>Line endings and keywords</li>
+</ul>
+
+</div>
+
+<!-- ==================================================================== -->
+<div class="h2">
+<h2 id="repos_creation">Repository creation</h2>
+
+<p>Create a new repository for holding versioned data.</p>
+
+<table class="sidebyside">
+<tr>
+ <th>CVS</th>
+ <th>Subversion</th>
+</tr>
+<tr>
+ <td>
+ <dl>
+ <dt>Commands:</dt>
+ <dd><tt>$&nbsp;cvs&nbsp;-d&nbsp;/usr/local/repos&nbsp;init</tt></dd>
+
+ <dt>Explanation:</dt>
+ <dd>Creates a new directory <tt>repos</tt> ready to hold RCS
+ files and config scripts.</dd>
+ </dl>
+ </td>
+ <td>
+ <dl>
+ <dt>Commands:</dt>
+ <dd><tt>$&nbsp;svnadmin&nbsp;create&nbsp;/usr/local/repos</tt></dd>
+
+ <dt>Explanation:</dt>
+ <dd>Creates a new directory <tt>repos</tt> containing BerkeleyDB
+ files and config scripts.</dd>
+ </dl>
+ </td>
+</tr>
+</table>
+
+<dl class="bookref">
+ <dt>Book References:</dt>
+ <dd><a href="http://svnbook.red-bean.com/svnbook/ch05s02.html">Repository Creation and Configuration</a></dd>
+</dl>
+
+</div>
+
+<!-- ==================================================================== -->
+<div class="h2">
+<h2 id="import">Importing data</h2>
+
+<p>Populate a new repository with initial data. Assuming that you
+ have a tree of code in the local directory <tt>myproj/</tt>, and
+ you want to move this tree into the repository.</p>
+
+<table class="sidebyside">
+<tr>
+ <th>CVS</th>
+ <th>Subversion</th>
+</tr>
+<tr>
+ <td>
+ <dl>
+ <dt>Commands:</dt>
+ <dd><tt>$&nbsp;cd&nbsp;myproj</tt></dd>
+ <dd><tt>$&nbsp;cvs&nbsp;-d&nbsp;/usr/local/repos&nbsp;import&nbsp;myproj/&nbsp;none&nbsp;start</tt></dd>
+
+ <dt>Explanation:</dt>
+
+ <dd>This copies the contents of the current working directory to
+ a new directory (<tt>myproj</tt>) in the CVS repository. The
+ CVS repository now contains a directory <tt>/myproj/</tt> at the
+ top level.</dd>
+
+ </dl>
+ </td>
+ <td>
+ <dl>
+ <dt>Commands:</dt>
+ <dd><tt>$&nbsp;svn&nbsp;mkdir&nbsp;file:///usr/local/repos/tags</tt></dd>
+ <dd><tt>$&nbsp;svn&nbsp;mkdir&nbsp;file:///usr/local/repos/branches</tt></dd>
+ <dd><tt>$&nbsp;svn&nbsp;import&nbsp;myproj/&nbsp;file:///usr/local/repos/trunk</tt></dd>
+
+ <dt>Explanation:</dt>
+
+ <dd>Though not strictly required, we deliberately create
+ <tt>/tags</tt> and <tt>/branches</tt> top-level directories in
+ the repository, to hold tags and branches later on. Then we
+ import the contents of the local <tt>myproj/</tt> directory into
+ a newly created <tt>/trunk</tt> directory in the
+ repository.</dd>
+ </dl>
+ </td>
+</tr>
+</table>
+
+<dl class="bookref">
+ <dt>Book References:</dt>
+ <dd><a href="http://svnbook.red-bean.com/svnbook/ch05s04.html#svn-ch-5-sect-6.1">Choosing a repository layout</a></dd>
+ <dd><a href="http://svnbook.red-bean.com/svnbook/re12.html">svn import</a></dd>
+</dl>
+</div>
+
+<!-- ==================================================================== -->
+<div class="h2">
+<h2 id="installing">Installing a server</h2>
+
+<p>Make the repository available to clients via a network.</p>
+
+<table class="sidebyside">
+<tr>
+ <th>CVS</th>
+ <th>Subversion</th>
+</tr>
+<tr>
+ <td>
+ <dl>
+ <dt>Commands:</dt>
+ <dd>(too complex to demonstrate here)</dd>
+
+ <dt>Explanation:</dt>
+ <dd>Export the repository via the cvs <em>pserver</em> program.
+ It can be launched by either <strong>inetd</strong> or a
+ client's <strong>ssh</strong> remote request.</dd>
+
+ </dl>
+ </td>
+ <td>
+ <dl>
+ <dt>Commands:</dt>
+ <dd>(too complex to demonstrate here)</dd>
+
+ <dt>Explanation:</dt>
+ <dd>Export the repository with the <em>Apache 2.0.x</em> server,
+ or via the <em>svnserve</em> program. The latter can run as a
+ standalone daemon, can be launched by <strong>inetd</strong>, or
+ invoked by a client's <strong>ssh</strong> remote request.</dd>
+
+ </dl>
+ </td>
+</tr>
+</table>
+
+<dl class="bookref">
+ <dt>Book References:</dt>
+ <dd><a href="http://svnbook.red-bean.com/svnbook/ch06.html">Server configuration</a></dd>
+</dl>
+
+</div>
+
+<!-- ==================================================================== -->
+<div class="h2">
+<h2 id="authenticating">Authenticating to a server</h2>
+
+<p>Have a network client prove its identity to a version
+ control server.</p>
+
+<table class="sidebyside">
+<tr>
+ <th>CVS</th>
+ <th>Subversion</th>
+</tr>
+<tr>
+ <td>
+ <dl>
+ <dt>Commands:</dt>
+ <dd><tt>$&nbsp;cvs&nbsp;-d&nbsp;:pserver:user@host:/repos&nbsp;<em>command</em>&hellip;</tt></dd>
+
+ <dt>Explanation:</dt>
+
+ <dd>When contacting a repository, the client pre-emptively
+ "pushes" its authentication credentials at the server.</dd>
+
+ </dl>
+ </td>
+ <td>
+ <dl>
+ <dt>Commands:</dt>
+ <dd><tt>$&nbsp;svn&nbsp;<em>command</em>&nbsp;<em>URL</em>&hellip;</tt></dd>
+ <dd><tt>Password&nbsp;for&nbsp;'user':&nbsp;&nbsp;XXXXXXX</tt></dd>
+
+ <dt>Explanation:</dt>
+
+ <dd>The client's authentication credentials are "pulled" from
+ the user interactively, and only when the server deems that a
+ challenge needs to be made. (And contrary to popular belief,
+ the <tt>--username</tt> and <tt>--password</tt> options are
+ merely values to be used <em>if</em> the server issues a
+ challenge; they do not "push" the credentials at the
+ server.)</dd>
+
+ </dl>
+ </td>
+</tr>
+</table>
+
+<dl class="bookref">
+ <dt>Book References:</dt>
+ <dd><a href="http://svnbook.red-bean.com/svnbook/ch06s02.html">Network Model</a></dd>
+</dl>
+
+</div>
+
+<!-- ==================================================================== -->
+<div class="h2">
+<h2 id="browsing">Browsing a repository</h2>
+
+<p>Browse the repository as a filesystem, perusing file
+ contents and history as well (older versions of files or
+ trees.)</p>
+
+<table class="sidebyside">
+<tr>
+ <th>CVS</th>
+ <th>Subversion</th>
+</tr>
+<tr>
+ <td>
+ <dl>
+ <dt>Commands:</dt>
+ <dd>(not possible with commandline client)</dd>
+
+ <dt>Explanation:</dt>
+
+ <dd>Not possible with commandline client. A third-party web
+ server tool such as ViewCVS must be used.</dd>
+
+ </dl>
+ </td>
+ <td>
+ <dl>
+ <dt>Commands:</dt>
+ <dd><tt>$&nbsp;svn&nbsp;list&nbsp;<em>URL</em>&nbsp;[-r&nbsp;<em>rev</em>]&nbsp;[-v]</tt></dd>
+ <dd><tt>$&nbsp;svn&nbsp;cat&nbsp;<em>URL</em>&nbsp;[-r&nbsp;<em>rev</em>]</tt></dd>
+
+ <dt>Explanation:</dt>
+
+ <dd>The <tt>svn list</tt> and <tt>svn cat</tt> commands allow
+ interactive browsing of a repository (and all previous states of
+ a repository) from the commandline. (The <tt>--verbose [-v]</tt>
+ switch displays full listing information.) If Apache is being
+ used as a Subversion server process (i.e. clients access via
+ <strong>http://</strong>), then the latest version of the
+ repository can be directly browsed by entering <em>URL</em> into
+ any web browser. Additionally, a third-party web server tool
+ (such as ViewCVS) can be used with Subversion.</dd>
+
+ </dl>
+ </td>
+</tr>
+</table>
+
+<dl class="bookref">
+ <dt>Book References:</dt>
+ <dd><a href="http://svnbook.red-bean.com/svnbook/re14.html">svn list</a></dd>
+</dl>
+
+</div>
+
+<!-- ==================================================================== -->
+<div class="h2">
+<h2 id="checkingout">Checking out a working copy</h2>
+
+<p>Create a workspace on local disk which mirrors a directory
+ in the repository.</p>
+
+<table class="sidebyside">
+<tr>
+ <th>CVS</th>
+ <th>Subversion</th>
+</tr>
+<tr>
+ <td>
+ <dl>
+ <dt>Commands:</dt>
+ <dd><tt>$&nbsp;cvs&nbsp;-d&nbsp;/usr/local/repos&nbsp;checkout&nbsp;myproj</tt></dd>
+ <dd><tt>U&nbsp;myproj/foo.c</tt></dd>
+ <dd><tt>U&nbsp;myproj/bar.c</tt></dd>
+ <dd><tt>&hellip;</tt></dd>
+
+ <dt>Explanation:</dt>
+
+ <dd>Creates a local directory <tt>myproj</tt> which is a mirror
+ of the repository directory <tt>/myproj</tt>.</dd>
+
+ </dl>
+ </td>
+ <td>
+ <dl>
+ <dt>Commands:</dt>
+ <dd><tt>$&nbsp;svn&nbsp;checkout&nbsp;file:///usr/local/repos/trunk&nbsp;myproj</tt></dd>
+ <dd><tt>A&nbsp;&nbsp;myproj/foo.c</tt></dd>
+ <dd><tt>A&nbsp;&nbsp;myproj/bar.c</tt></dd>
+ <dd><tt>&hellip;</tt></dd>
+
+ <dt>Explanation:</dt>
+
+ <dd>Assuming that the original project data was imported into
+ the repository <tt>/trunk</tt> directory, this creates a local
+ directory <tt>myproj</tt> which is a mirror of the repository
+ directory <tt>/trunk</tt>. Standard Subversion convention is to
+ do "mainline" development in <tt>/trunk</tt>. See branching and
+ tagging sections for more details.</dd>
+
+ </dl>
+ </td>
+</tr>
+</table>
+
+<dl class="bookref">
+ <dt>Book References:</dt>
+ <dd><a href="http://svnbook.red-bean.com/svnbook/ch03s04.html">Initial Checkout</a></dd>
+ <dd><a href="http://svnbook.red-bean.com/svnbook/re04.html">svn checkout</a></dd>
+</dl>
+
+</div>
+
+<!-- ==================================================================== -->
+<div class="h2">
+<h2 id="changeditems">Seeing locally changed items</h2>
+
+<p>Discover which items in the working copy have local
+ modifications or are scheduled for addition/deletion.</p>
+
+<table class="sidebyside">
+<tr>
+ <th>CVS</th>
+ <th>Subversion</th>
+</tr>
+<tr>
+ <td>
+ <dl>
+ <dt>Commands:</dt>
+ <dd><tt>$&nbsp;cvs&nbsp;status</tt></dd>
+ <dd><tt>&hellip;</tt></dd>
+ <dd><tt>File: baz.c&nbsp;&nbsp;&nbsp;Status:&nbsp;Up-to-date</tt></dd>
+ <dd><tt>&hellip;</tt></dd>
+ <dd><tt>$&nbsp;cvs&nbsp;update</tt></dd>
+ <dd><tt>M foo.c</tt></dd>
+ <dd><tt>U bar.c</tt></dd>
+ <dd><tt>&hellip;</tt></dd>
+
+ <dt>Explanation:</dt>
+
+ <dd>The <tt>cvs status</tt> command shows whether a file is
+ locally modified or out of date, including information about
+ working revision and branch info. Unfortunately, because the
+ output is so verbose and hard to read, many users run <tt>cvs
+ update</tt> instead, which shows a more compact listing of
+ modified files (and of course, it also causes the server to
+ merge changes into your working copy.)</dd>
+
+ </dl>
+ </td>
+ <td>
+ <dl>
+ <dt>Commands:</dt>
+ <dd><tt>$&nbsp;svn&nbsp;status</tt></dd>
+ <dd><tt>M&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;foo.c</tt></dd>
+ <dd><tt>&hellip;</tt></dd>
+
+ <dt>Explanation:</dt>
+
+ <dd>Shows modified files only. Very fast, as it does not use
+ the network. Does not update your working copy, yet still shows
+ a single-line display, much like <tt>svn update</tt>. To see
+ working revision and branch information, run <tt>svn info</tt>.</dd>
+
+ </dl>
+ </td>
+</tr>
+</table>
+
+<dl class="bookref">
+ <dt>Book References:</dt>
+ <dd><a href="http://svnbook.red-bean.com/svnbook/ch03s05.html#svn-ch-3-sect-4.3.1">Examine Your Changes</a></dd>
+ <dd><a href="http://svnbook.red-bean.com/svnbook/re26.html">svn status</a></dd>
+</dl>
+
+</div>
+
+<!-- ==================================================================== -->
+<div class="h2">
+<h2 id="outofdate">Seeing out-of-date items</h2>
+
+<p>Discover which items in the working copy are out-of-date
+ (i.e. newer versions exist in the repository.)</p>
+
+<table class="sidebyside">
+<tr>
+ <th>CVS</th>
+ <th>Subversion</th>
+</tr>
+<tr>
+ <td>
+ <dl>
+ <dt>Commands:</dt>
+ <dd><tt>$&nbsp;cvs&nbsp;status</tt></dd>
+ <dd><tt>&hellip;</tt></dd>
+ <dd><tt>File: baz.c&nbsp;&nbsp;&nbsp;Status:&nbsp;Needs&nbsp;Patch</tt></dd>
+ <dd><tt>&hellip;</tt></dd>
+ <dd><tt>$&nbsp;cvs&nbsp;-n&nbsp;update</tt></dd>
+ <dd><tt>M foo.c</tt></dd>
+ <dd><tt>U bar.c</tt></dd>
+ <dd><tt>&hellip;</tt></dd>
+
+ <dt>Explanation:</dt>
+
+ <dd>The <tt>cvs status</tt> command shows whether a file is
+ locally modified or out of date, including information about
+ working revision and branch info. A less verbose option is to
+ run <tt>cvs -n update</tt> instead, which shows a compact
+ listing of both out-of-date and locally modified files, without
+ actually updating the working copy.</dd>
+
+ </dl>
+ </td>
+ <td>
+ <dl>
+ <dt>Commands:</dt>
+ <dd><tt>$&nbsp;svn&nbsp;status&nbsp;-u</tt></dd>
+ <dd><tt>M&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;46&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;foo.c</tt></dd>
+ <dd><tt>M&nbsp;&nbsp;*&nbsp;&nbsp;46&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bar.c</tt></dd>
+ <dd><tt>&nbsp;&nbsp;&nbsp;*&nbsp;&nbsp;46&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;baz.c</tt></dd>
+ <dd><tt>&hellip;</tt></dd>
+
+ <dt>Explanation:</dt>
+
+ <dd>Shows modified files (<tt>M</tt>) as well as out-of-date
+ files (<tt>*</tt>). Contacts repository, but doesn't modify the
+ working copy. To see working revision and branch information,
+ run <tt>svn info</tt>.</dd>
+
+ </dl>
+ </td>
+</tr>
+</table>
+
+<dl class="bookref">
+ <dt>Book References:</dt>
+ <dd><a href="http://svnbook.red-bean.com/svnbook/ch03s05.html#svn-ch-3-sect-4.3.1">Examine Your Changes</a></dd>
+ <dd><a href="http://svnbook.red-bean.com/svnbook/re26.html">svn status</a></dd>
+</dl>
+
+</div>
+
+<!-- ==================================================================== -->
+<div class="h2">
+<h2 id="scheduling">Scheduling additions or deletions</h2>
+
+<p>Schedule a working-copy file or directory to be added or
+ removed from the repository.</p>
+
+<table class="sidebyside">
+<tr>
+ <th>CVS</th>
+ <th>Subversion</th>
+</tr>
+<tr>
+ <td>
+ <dl>
+ <dt>Commands:</dt>
+ <dd><tt>$&nbsp;touch&nbsp;foo.c</tt></dd>
+ <dd><tt>$&nbsp;cvs&nbsp;add&nbsp;foo.c</tt></dd>
+ <dd><tt>cvs&nbsp;server:&nbsp;scheduling&nbsp;file&nbsp;`blah'&nbsp;for&nbsp;addition</tt></dd>
+ <dd><tt>cvs&nbsp;server:&nbsp;use&nbsp;'cvs&nbsp;commit'&nbsp;to&nbsp;add&nbsp;this&nbsp;file&nbsp;permanently</tt></dd>
+ <dd><tt>&nbsp;</tt></dd>
+ <dd><tt>$&nbsp;mkdir&nbsp;new-dir</tt></dd>
+ <dd><tt>$&nbsp;cvs&nbsp;add&nbsp;new-dir</tt></dd>
+ <dd><tt>Directory&nbsp;new-dir&nbsp;added&nbsp;to&nbsp;the&nbsp;repository</tt></dd>
+ <dd><tt>&nbsp;</tt></dd>
+ <dd><tt>$&nbsp;rm&nbsp;bar.c</tt></dd>
+ <dd><tt>$&nbsp;cvs&nbsp;rm&nbsp;bar.c</tt></dd>
+ <dd><tt>cvs&nbsp;remove:&nbsp;scheduling&nbsp;`bar.c'&nbsp;for&nbsp;removal</tt></dd>
+ <dd><tt>cvs&nbsp;remove:&nbsp;use&nbsp;'cvs&nbsp;commit'&nbsp;to&nbsp;remove&nbsp;this&nbsp;file&nbsp;permanently</tt></dd>
+ <dd><tt>&nbsp;</tt></dd>
+ <dd><tt>$&nbsp;rm&nbsp;-rf&nbsp;old-dir/*</tt></dd>
+ <dd><tt>$&nbsp;cvs&nbsp;rm&nbsp;old-dir</tt></dd>
+ <dd><tt>cvs&nbsp;remove:&nbsp;Removing&nbsp;3bits</tt></dd>
+ <dd><tt>&hellip;</tt></dd>
+
+
+ <dt>Explanation:</dt>
+
+ <dd>Schedules a file or directory for addition or removal
+ to/from the repository. The repository will not be changed
+ until the user runs <tt>cvs commit</tt>, except for the case of
+ adding a directory, which immediately changes the repository.
+ Also, directories cannot be truly removed from the repository,
+ just emptied out. (<tt>cvs update -P</tt> will prune empty
+ directories from your working copy.)</dd>
+
+ </dl>
+ </td>
+ <td>
+ <dl>
+ <dt>Commands:</dt>
+ <dd><tt>$&nbsp;touch&nbsp;foo.c</tt></dd>
+ <dd><tt>$&nbsp;svn&nbsp;add&nbsp;foo.c</tt></dd>
+ <dd><tt>A&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;foo.c</tt></dd>
+ <dd><tt>&nbsp;</tt></dd>
+ <dd><tt>$&nbsp;mkdir&nbsp;new-dir</tt></dd>
+ <dd><tt>$&nbsp;svn&nbsp;add&nbsp;new-dir</tt></dd>
+ <dd><tt>A&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;new-dir</tt></dd>
+ <dd><tt>&nbsp;</tt></dd>
+ <dd><tt>$&nbsp;svn&nbsp;rm&nbsp;bar.c</tt></dd>
+ <dd><tt>D&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bar.c</tt></dd>
+ <dd><tt>&nbsp;</tt></dd>
+ <dd><tt>$&nbsp;svn&nbsp;rm&nbsp;old-dir</tt></dd>
+ <dd><tt>D&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;old-dir/file1</tt></dd>
+ <dd><tt>D&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;old-dir/file2</tt></dd>
+ <dd><tt>&hellip;</tt></dd>
+
+ <dt>Explanation:</dt>
+
+ <dd>Schedules a file or directory for addition or removal
+ to/from the repository. The repository will not be changed
+ until the user runs <tt>svn commit</tt>. The scheduled
+ operations are shown as <tt>A</tt> or <tt>D</tt> by <tt>svn
+ status</tt>, and <tt>svn revert</tt> can un-do the scheduling.
+ Directories really can be deleted (though as with all deleted
+ items, continues to exist in history.)</dd>
+
+ </dl>
+ </td>
+</tr>
+</table>
+
+<dl class="bookref">
+ <dt>Book References:</dt>
+ <dd><a href="http://svnbook.red-bean.com/svnbook/ch03s05.html#svn-ch-3-sect-4.2">Make Changes to Your Working Copy</a></dd>
+ <dd><a href="http://svnbook.red-bean.com/svnbook/re01.html">svn add</a></dd>
+ <dd><a href="http://svnbook.red-bean.com/svnbook/re08.html">svn delete</a></dd>
+</dl>
+
+</div>
+
+<!-- ==================================================================== -->
+<div class="h2">
+<h2 id="copying">Copying and moving</h2>
+
+<p>Copy or move/rename a file or directory.</p>
+
+<table class="sidebyside">
+<tr>
+ <th>CVS</th>
+ <th>Subversion</th>
+</tr>
+<tr>
+ <td>
+ <dl>
+ <dt>Commands:</dt>
+ <dd>(not possible.)</dd>
+
+
+ <dt>Explanation:</dt>
+
+ <dd>Not possible, unless an administrator directly mucks with
+ RCS files in the repository. (And in that case, no history
+ records the act of copying or renaming.)</dd>
+
+ </dl>
+ </td>
+ <td>
+ <dl>
+ <dt>Commands:</dt>
+ <dd><tt>$&nbsp;svn&nbsp;copy&nbsp;foo.c&nbsp;foo2.c</tt></dd>
+ <dd><tt>A&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;foo2.c</tt></dd>
+ <dd><tt>&nbsp;</tt></dd>
+ <dd><tt>$&nbsp;svn&nbsp;copy&nbsp;dir&nbsp;dir2</tt></dd>
+ <dd><tt>A&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;dir2</tt></dd>
+ <dd><tt>&nbsp;</tt></dd>
+ <dd><tt>$&nbsp;svn&nbsp;move&nbsp;bar.c&nbsp;baz.c</tt></dd>
+ <dd><tt>A&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;baz.c</tt></dd>
+ <dd><tt>D&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;bar.c</tt></dd>
+ <dd><tt>&nbsp;</tt></dd>
+ <dd><tt>$&nbsp;svn&nbsp;move&nbsp;dirA&nbsp;dirB</tt></dd>
+ <dd><tt>A&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;dirB</tt></dd>
+ <dd><tt>D&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;dirA/file1</tt></dd>
+ <dd><tt>D&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;dirA/file2</tt></dd>
+ <dd><tt>&hellip;</tt></dd>
+
+ <dt>Explanation:</dt>
+
+ <dd>The <tt>svn copy</tt> command schedules a file or directory
+ for addition to the repository, recording the "source" of the
+ copy. After committing, <tt>svn log</tt> on the copied item
+ will trace history back through the original copy-source. The
+ <tt>svn move</tt> command is exactly equivalent to running
+ <tt>svn copy</tt>, followed by an <tt>svn delete</tt> on the
+ copy-source: the result is a new item scheduled for addition
+ (with copy-history attached) and the original item scheduled for
+ deletion.</dd>
+
+ </dl>
+ </td>
+</tr>
+</table>
+
+<dl class="bookref">
+ <dt>Book References:</dt>
+ <dd><a href="http://svnbook.red-bean.com/svnbook/ch03s05.html#svn-ch-3-sect-4.2">Make Changes to Your Working Copy</a></dd>
+ <dd><a href="http://svnbook.red-bean.com/svnbook/re07.html">svn copy</a></dd>
+ <dd><a href="http://svnbook.red-bean.com/svnbook/re18.html">svn move</a></dd>
+</dl>
+
+
+</div>
+
+<!-- ==================================================================== -->
+<div class="h2">
+<h2>Finding the beginning of a branch</h2>
+
+<p>If you're attempting to merge an entire branch into another, you
+need to compare the "root" and "tip" of the source branch, and then
+merge those differences into a working copy of the target branch.
+Obviously the "tip" of the branch can be represented by using the
+<tt>HEAD</tt> keyword. But how do you find the "birth" revision of
+the source branch?</p>
+
+<p>The easiest solution is to run</p>
+
+<pre>
+ $ svn log -v --stop-on-copy source-branch-URL
+ &hellip;
+</pre>
+
+<p>This command will display every change ever made to the branch, but
+<tt>--stop-on-copy</tt> option will cause the output to stop as soon
+as detects a copy operation in the branch's history. By definition,
+then, the very last log entry printed will show the copy being made.
+It will look something like:</p>
+
+<pre>
+r9189 | joe | 2004-03-22 10:10:47 -0600 (Mon, 22 Mar 2004) | 1 line
+Changed paths:
+ A /branches/mybranch (from /trunk:9188)
+</pre>
+
+<p>In this case, you would then know to compare revisions 9189 and
+HEAD of the branch in order to perform the merge:</p>
+
+<pre>
+ $ svn merge -r9189:HEAD source-branch-URL target-branch-WC
+ &hellip;
+</pre>
+
+</div>
+
+<!-- ==================================================================== -->
+<div class="h2">
+<h2>Seeing all of a project's tags</h2>
+
+<p>Assuming you've been following a consistent policy for creating
+tag-copies, then this is just a matter of running <tt>svn ls</tt> on a
+directory containing your tags. Typically you would run it on the
+<tt>/tags</tt> directory in your repository, although you're certainly
+free to organize this directory in a more complex way, or invent a
+different convention altogether.</p>
+
+<p>As an example, you can see all of Subversion's tags by running:</p>
+
+<pre>
+ $ svn ls --verbose http://svn.apache.org/repos/asf/subversion/tags
+ &hellip;
+ 7739 kfogel Nov 13 22:05 0.33.0/
+ 7796 josander Nov 18 12:15 0.33.1/
+ 7932 josander Dec 03 17:54 0.34.0/
+ 8045 josander Dec 19 15:13 0.35.0/
+ 8063 josander Dec 20 11:20 0.35.1/
+ 8282 josander Jan 13 14:15 0.36.0/
+ 8512 josander Jan 24 17:31 0.37.0/
+ 8810 kfogel Feb 23 03:44 1.0.0/
+ &hellip;
+</pre>
+
+</div>
+
+<!-- ==================================================================== -->
+<div class="h2">
+<h2>Seeing the differences between two tags</h2>
+
+<p>Just use <tt>svn diff</tt> in its fully expanded form, which
+compares any two URLs:</p>
+
+<pre>
+ $ svn diff tagURL1 tagURL2
+ &hellip;
+</pre>
+
+</div>
+
+<!-- ==================================================================== -->
+<div class="h2">
+<h2>Seeing logs between two tags</h2>
+
+<p>This is a somewhat common practice in CVS, and is doable in Subversion,
+but requires a little bit more work. Assuming that you've made two
+tags of <tt>/trunk</tt> at different points in time, the ultimate goal
+here is to run </p>
+
+<pre>
+ $ svn log -rX:Y trunkURL
+</pre>
+
+<p>&hellip;where X and Y are the revisions from which the two tags were
+copied. To discover X and Y, you can use the same technique
+described in the previous section ("finding the beginning of a
+branch".) Just use the <tt>--stop-on-copy</tt> option when logging the
+history of each tag. No commits happen on tag directories, so the
+following commands should each produce exactly <em>one</em> log
+entry:</p>
+
+<pre>
+ $ svn log -v --stop-on-copy tag1-URL
+
+ r3520 | joe | 2004-03-12 15:28:43 -0600 (Fri, 12 Mar 2004) | 1 line
+ &hellip;
+
+ $ svn log -v --stop-on-copy tag2-URL
+ a
+ r4177 | joe | 2004-03-12 15:28:43 -0600 (Fri, 12 Mar 2004) | 1 line
+ &hellip;
+</pre>
+
+<p>So in this example, the values of X and Y are 3520 and 4177. Now
+you can view all <tt>/trunk</tt> changes between those two points in time:</p>
+
+<pre>
+ $ svn log -r3520:4177 trunkURL
+ &hellip;
+</pre>
+
+</div>
+
+<!-- ==================================================================== -->
+<div class="h2">
+<h2>Fixing an incorrect tag</h2>
+
+<p>If your tag is a bit off, you can "adjust" it just as people often
+do in CVS. Simply check out a working copy of the tag directory, make
+any changes you wish, and commit.</p>
+
+<p>Remember, because branches and tags are directories, they can also
+be deleted when they're no longer of any use to your project. They'll
+continue to exist in the repository's history.</p>
+
+
+</div>
+
+<!-- ==================================================================== -->
+<div class="h2">
+<h2>Creating/using "modules"</h2>
+
+<p>Compare CVS Modules vs. svn:externals.</p>
+
+</div>
+
+<!-- ==================================================================== -->
+</body>
+</html>
diff --git a/doc/user/lj_article.txt b/doc/user/lj_article.txt
new file mode 100644
index 000000000000..dca776d8947a
--- /dev/null
+++ b/doc/user/lj_article.txt
@@ -0,0 +1,323 @@
+
+ The Subversion Project: Building a Better CVS
+ ==============================================
+
+ Ben Collins-Sussman <sussman@collab.net>
+
+ Written in August 2001
+ Published in Linux Journal, January 2002
+
+Abstract
+--------
+
+This article discusses the history, goals, features and design of
+Subversion (http://subversion.tigris.org), an open-source project that
+aims to produce a compelling replacement for CVS.
+
+
+Introduction
+------------
+
+If you work on any kind of open-source project, you've probably worked
+with CVS. You probably remember the first time you learned to do an
+anonymous checkout of a source tree over the net -- or your first
+commit, or learning how to look at CVS diffs. And then the fateful
+day came: you asked your friend how to rename a file.
+
+"You can't", was the reply.
+
+What? What do you mean?
+
+"Well, you can delete the file from the repository and then re-add it
+under a new name."
+
+Yes, but then nobody would know it had been renamed...
+
+"Let's call the CVS administrator. She can hand-edit the repository's
+RCS files for us and possibly make things work."
+
+What?
+
+"And by the way, don't try to delete a directory either."
+
+You rolled your eyes and groaned. How could such simple tasks be
+difficult?
+
+
+The Legacy of CVS
+-----------------
+
+No doubt about it, CVS has evolved into the standard Software
+Configuration Management (SCM) system of the open source community.
+And rightly so! CVS itself is Free software, and its wonderful "non
+locking" development model -- whereby dozens of far-flung programmers
+collaborate -- fits the open-source world very well. In fact, one
+might argue that without CVS, it's doubtful whether sites like
+Freshmeat or Sourceforge would ever have flourished as they do now.
+CVS and its semi-chaotic development model have become an essential
+part of open source culture.
+
+So what's wrong with CVS?
+
+Because it uses the RCS storage-system under the hood, CVS can only
+track file contents, not tree structures. As a result, the user has
+no way to copy, move, or rename items without losing history. Tree
+rearrangements are always ugly server-side tweaks.
+
+The RCS back-end cannot store binary files efficiently, and branching
+and tagging operations can grow to be very slow. CVS also uses the
+network inefficiently; many users are annoyed by long waits, because
+file differeces are sent in only one direction (from server to client,
+but not from client to server), and binary files are always
+transmitted in their entirety.
+
+From a developer's standpoint, the CVS codebase is the result of
+layers upon layers of historical "hacks". (Remember that CVS began
+life as a collection of shell-scripts to drive RCS.) This makes the
+code difficult to understand, maintain, or extend. For example: CVS's
+networking ability was essentially "stapled on". It was never
+designed to be a native client-server system.
+
+Rectifying CVS's problems is a huge task -- and we've only listed just
+a few of the many common complaints here.
+
+
+Enter Subversion
+----------------
+
+In 1995, Karl Fogel and Jim Blandy founded Cyclic Software, a company
+for commercially supporting and improving CVS. Cyclic made the first
+public release of a network-enabled CVS (contributed by Cygnus
+software.) In 1999, Karl Fogel published a book about CVS and the
+open-source development model it enables (cvsbook.red-bean.com). Karl
+and Jim had long talked about writing a replacement for CVS; Jim had
+even drafted a new, theoretical repository design. Finally, in
+February of 2000, Brian Behlendorf of CollabNet (www.collab.net)
+offered Karl a full-time job to write a CVS replacement. Karl
+gathered a team together and work began in May.
+
+The team settled on a few simple goals: it was decided that Subversion
+would be designed as a functional replacement for CVS. It would do
+everything that CVS does -- preserving the same development model
+while fixing the flaws in CVS's (lack-of) design. Existing CVS users
+would be the target audience: any CVS user should be able to start
+using Subversion with little effort. Any other SCM "bonus features"
+were decided to be of secondary importance (at least before a 1.0
+release.)
+
+At the time of writing, the original team has been coding for a little
+over a year, and we have a number of excellent volunteer contributors.
+(Subversion, like CVS, is a open-source project!)
+
+
+Subversion's Features
+----------------------
+
+Here's a quick run-down of some of the reasons you should be excited
+about Subversion:
+
+ * Real copies and renames. The Subversion repository doesn't use
+ RCS files at all; instead, it implements a 'virtual' versioned
+ filesystem that tracks tree-structures over time (described
+ below). Files *and* directories are versioned. At last, there
+ are real client-side `mv' and `cp' commands that behave just as
+ you think.
+
+ * Atomic commits. A commit either goes into the repository
+ completely, or not all.
+
+ * Advanced network layer. The Subversion network server is Apache,
+ and client and server speak WebDAV(2) to one another. (See the
+ 'design' section below.)
+
+ * Faster network access. A binary diffing algorithm is used to
+ store and transmit deltas in *both* directions, regardless of
+ whether a file is of text or binary type.
+
+ * Filesystem "properties". Each file or directory has an invisible
+ hashtable attached. You can invent and store any arbitrary
+ key/value pairs you wish: owner, perms, icons, app-creator,
+ mime-type, personal notes, etc. This is a general-purpose feature
+ for users. Properties are versioned, just like file contents.
+ And some properties are auto-detected, like the mime-type of a
+ file (no more remembering to use the '-kb' switch!)
+
+ * Extensible and hackable. Subversion has no historical baggage; it
+ was designed and then implemented as a collection of shared C
+ libraries with well-defined APIs. This makes Subversion extremely
+ maintainable and usable by other applications and languages.
+
+ * Easy migration. The Subversion command-line client is very
+ similar to CVS; the development model is the same, so CVS users
+ should have little trouble making the switch. Development of a
+ 'cvs2svn' repository converter is in progress.
+
+ * It's Free. Subversion is released under a Apache/BSD-style
+ open-source license.
+
+
+Subversion's Design
+-------------------
+
+Subversion has a modular design; it's implemented as a collection of C
+libraries. Each layer has a well-defined purpose and interface. In
+general, code flow begins at the top of the diagram and flows
+"downward" -- each layer provides an interface to the layer above it.
+
+ <<insert diagram here: svn.tiff>>
+
+
+Let's take a short tour of these layers, starting at the bottom.
+
+
+--> The Subversion filesystem.
+
+The Subversion Filesystem is *not* a kernel-level filesystem that one
+would install in an operating system (like the Linux ext2 fs.)
+Instead, it refers to the design of Subversion's repository. The
+repository is built on top of a database -- currently Berkeley DB --
+and thus is a collection of .db files. However, a library accesses
+these files and exports a C API that simulates a filesystem --
+specifically, a "versioned" filesystem.
+
+This means that writing a program to access the repository is like
+writing against other filesystem APIs: you can open files and
+directories for reading and writing as usual. The main difference is
+that this particular filesystem never loses data when written to; old
+versions of files and directories are always saved as historical
+artifacts.
+
+Whereas CVS's backend (RCS) stores revision numbers on a per-file
+basis, Subversion numbers entire trees. Each atomic 'commit' to the
+repository creates a completely new filesystem tree, and is
+individually labeled with a single, global revision number. Files and
+directories which have changed are rewritten (and older versions are
+backed up and stored as differences against the latest version), while
+unchanged entries are pointed to via a shared-storage mechanism. This
+is how the repository is able to version tree structures, not just
+file contents.
+
+Finally, it should be mentioned that using a database like Berkeley DB
+immediately provides other nice features that Subversion needs: data
+integrity, atomic writes, recoverability, and hot backups. (See
+www.sleepycat.com for more information.)
+
+
+--> The network layer.
+
+Subversion has the mark of Apache all over it. At its very core, the
+client uses the Apache Portable Runtime (APR) library. (In fact, this
+means that Subversion client should compile and run anywhere Apache
+httpd does -- right now, this list includes all flavors of Unix,
+Win32, BeOS, OS/2, Mac OS X, and possibly Netware.)
+
+However, Subversion depends on more than just APR -- the Subversion
+"server" is Apache httpd itself.
+
+Why was Apache chosen? Ultimately, the decision was about not
+reinventing the wheel. Apache is a time-tested, open-source server
+process that ready for serious use, yet is still extensible. It can
+sustain a high network load. It runs on many platforms and can
+operate through firewalls. It's able to use a number of different
+authentication protocols. It can do network pipelining and caching.
+By using Apache as a server, Subversion gets all these features for
+free. Why start from scratch?
+
+Subversion uses WebDAV as its network protocol. DAV (Distributed
+Authoring and Versioning) is a whole discussion in itself (see
+www.webdav.org) -- but in short, it's an extension to HTTP that allows
+reads/writes and "versioning" of files over the web. The Subversion
+project is hoping to ride a slowly rising tide of support for this
+protocol: all of the latest file-browsers for Win32, MacOS, and GNOME
+speak this protocol already. Interoperability will (hopefully) become
+more and more of a bonus over time.
+
+For users who simply wish to access Subversion repositories on local
+disk, the client can do this too; no network is required. The
+"Repository Access" layer (RA) is an abstract API implemented by both
+the DAV and local-access RA libraries. This is a specific benefit of
+writing a "librarized" version control system; it's a big win over
+CVS, which has two very different, difficult-to-maintain codepaths for
+local vs. network repository-access. Feel like writing a new network
+protocol for Subversion? Just write a new library that implements the
+RA API!
+
+
+--> The client libraries.
+
+On the client side, the Subversion "working copy" library maintains
+administrative information within special SVN/ subdirectories, similar
+in purpose to the CVS/ administrative directories found in CVS working
+copies.
+
+A glance inside the typical SVN/ directory turns up a bit more than
+usual, however. The `entries' file contains XML which describes the
+current state of the working copy directory (and which basically
+serves the purposes of CVS's Entries, Root, and Repository files
+combined). But other items present (and not found in CVS/) include
+storage locations for the versioned "properties" (the metadata
+mentioned in 'Subversion Features' above) and private caches of
+pristine versions of each file. This latter feature provides the
+ability to report local modifications -- and do reversions --
+*without* network access. Authentication data is also stored within
+SVN/, rather than in a single .cvspass-like file.
+
+The Subversion "client" library has the broadest responsibility; its
+job is to mingle the functionality of the working-copy library with
+that of the repository-access library, and then to provide a
+highest-level API to any application that wishes to perform general
+version control actions.
+
+For example: the C routine `svn_client_checkout()' takes a URL as an
+argument. It passes this URL to the repository-access library and
+opens an authenticated session with a particular repository. It then
+asks the repository for a certain tree, and sends this tree into the
+working-copy library, which then writes a full working copy to disk
+(SVN/ directories and all.)
+
+The client library is designed to be used by any application. While
+the Subversion source code includes a standard command-line client, it
+should be very easy to write any number of GUI clients on top of the
+client library. Hopefully, these GUIs should someday prove to be much
+better than the current crop of CVS GUI applications (the majority of
+which are no more than fragile "wrappers" around the CVS command-line
+client.)
+
+In addition, proper SWIG bindings (www.swig.org) should make
+the Subversion API available to any number of languages: java, perl,
+python, guile, and so on. In order to Subvert CVS, it helps to be
+ubiquitous!
+
+
+Subversion's Future
+-------------------
+
+The release of Subversion 1.0 is currently planned for early 2002.
+After the release of 1.0, Subversion is slated for additions such as
+i18n support, "intelligent" merging, better "changeset" manipulation,
+client-side plugins, and improved features for server administration.
+(Also on the wishlist is an eclectic collection of ideas, such as
+distributed, replicating repositories.)
+
+A final thought from Subversion's FAQ:
+
+ "We aren't (yet) attempting to break new ground in SCM systems, nor
+ are we attempting to imitate all the best features of every SCM
+ system out there. We're trying to replace CVS."
+
+If, in three years, Subversion is widely presumed to be the "standard"
+SCM system in the open-source community, then the project will have
+succeeded. But the future is still hazy: ultimately, Subversion
+will have to win this position on its own technical merits.
+
+Patches are welcome.
+
+
+For More Information
+--------------------
+
+Please visit the Subversion project website at
+http://subversion.tigris.org. There are discussion lists to join, and
+the source code is available via anonymous CVS -- and soon through
+Subversion itself.
+
diff --git a/doc/user/svn-best-practices.html b/doc/user/svn-best-practices.html
new file mode 100644
index 000000000000..61ba1c6e53a5
--- /dev/null
+++ b/doc/user/svn-best-practices.html
@@ -0,0 +1,350 @@
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
+ "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
+<title>Subversion Best Practices</title>
+<style type="text/css">
+h1 {
+ text-align: center;
+}
+</style>
+</head>
+
+<body>
+
+<h1>Subversion Best Practices</h1>
+
+<p>This is a quick set of guidelines for making the best use of
+Subversion in your day-to-day software development work.</p>
+
+
+<h2>Use a sane repository layout</h2>
+
+<p>There are many ways to lay out your repository. Because branches
+and tags are ordinary directories, you'll need to account for them in
+your repository structure.</p>
+
+<p>The Subversion project officially recommends the idea of a "project
+root", which represents an anchoring point for a project. A "project
+root" contains exactly three subdirectories: <tt>/trunk</tt>,
+<tt>/branches</tt>, and <tt>/tags</tt>. A repository may contain
+only one project root, or it may contain a number of them.</p>
+
+<p><em>Book reference:</em> <a
+ href="http://svnbook.red-bean.com/svnbook/ch05s04.html#svn-ch-5-sect-6.1">Choosing
+ a Repository Layout</a>.</p>
+
+
+
+<!-- =================================================== -->
+
+<h2>Commit logical changesets</h2>
+
+<p>When you commit a change to the repository, make sure your change
+reflects a single purpose: the fixing of a specific bug, the addition
+of a new feature, or some particular task. Your commit will create a
+new revision number which can forever be used as a "name" for the
+change. You can mention this revision number in bug databases, or use
+it as an argument to <tt>svn merge</tt> should you want to undo the
+change or port it to another branch.</p>
+
+<p><em>Book reference:</em> "Subversion and Changesets" sidebar,
+ within <a
+ href="http://svnbook.red-bean.com/svnbook/ch04s03.html">chapter
+ 4</a>.</p>
+
+<!-- =================================================== -->
+
+<h2>Use the issue-tracker wisely</h2>
+
+<p>Try to create as many two-way links between Subversion changesets
+and your issue-tracking database as possible:</p>
+
+<ul>
+<li>If possible, refer to a specific issue ID in every commit log message.</li>
+<li>When appending information to an issue (to describe progress, or
+ to close the issue) name the revision number(s) responsible
+ for the change.</li>
+</ul>
+
+<!-- =================================================== -->
+
+<h2>Track merges manually</h2>
+
+<p>When committing the result of a merge, be sure to write a
+descriptive log message that explains what was merged, something
+like:</p>
+
+ <pre>Merged revisions 3490:4120 of /branches/foobranch to /trunk.</pre>
+
+<p><em>Book reference:</em> <a
+ href="http://svnbook.red-bean.com/svnbook/ch04s03.html#svn-ch-4-sect-3.2">Tracking
+ merges manually</a>, and <a
+ href="http://svnbook.red-bean.com/svnbook/ch04s04.html#svn-ch-4-sect-4.1">Merging a whole branch to another</a>.</p>
+
+<!-- =================================================== -->
+
+<h2>Understand mixed-revision working copies</h2>
+
+<p>Your working copy's directories and files can be at different
+"working" revisions: this is a deliberate feature which allows you to
+mix and match older versions of things with newer ones. But there are
+few facts you must be aware of:</p>
+
+<ol>
+
+<li>After every <tt>svn commit</tt>, your working copy has mixed
+revisions. The things you just committed are now at the HEAD
+revision, and everything else is at an older revision.</li>
+
+<li>Certain commits are disallowed:
+ <ul>
+ <li>You cannot commit the deletion of a file or directory which
+ doesn't have a working revision of HEAD.</li>
+ <li>You cannot commit a property change to a directory which
+ doesn't have a working revision of HEAD.</li>
+ </ul>
+</li>
+
+<li><tt>svn update</tt> will bring your entire working copy to one
+ working revision, and is the typical solution to the
+ problems mentioned in point #2.</li>
+</ol>
+
+<p><em>Book reference:</em> <a
+href="http://svnbook.red-bean.com/svnbook/ch02s03.html#svn-ch-2-sect-3.4">The
+ limitation of mixed revisions</a>.</p>
+
+
+<!-- =================================================== -->
+
+<h2>Be patient with large files</h2>
+
+<p>A nice feature of Subversion is that by design, there is no limit
+to the size of files it can handle. Files are sent "streamily" in
+both directions between Subversion client and server, using a small,
+constant amount of memory on each side of the network.</p>
+
+<p>Of course, there are a number of practical issues to consider.
+While there's no need to worry about files in the kilobyte-sized range
+(e.g. typical source-code files), committing larger files can take a
+tremendous amount of both time and space (e.g. files that are dozens
+or hundreds of megabytes large.)</p>
+
+<p>To begin with, remember that your Subversion working copy stores
+pristine copies of all version-controlled files in the
+<tt>.svn/text-base/</tt> area. This means that your working copy
+takes up at least twice as much disk space as the original dataset.
+Beyond that, the Subversion client follows a (currently unadjustable)
+algorithm for committing files:</p>
+
+ <ul>
+ <li>Copies the file to <tt>.svn/tmp/</tt> <em>(can take a while,
+ and temporarily uses extra disk space)</em>)</li>
+
+ <li>Performs a binary diff between the tmpfile and the pristine
+ copy, or between the tmpfile and an empty-file if newly
+ added. <em>(can take a very long time to compute, even
+ though only a small amount of data might ultimately be sent
+ over the network)</em></li>
+
+ <li>Sends the diff to the server, then moves the tmpfile into
+ <tt>.svn/text-base/</tt></li>
+ </ul>
+
+<p>So while there's no theoretical limit to the size of your files,
+you'll need to be aware that very large files may require quite a bit
+of patient waiting while your client chugs away. You can rest
+assured, however, that unlike CVS, your large files won't incapacitate
+the server or affect other users.</p>
+
+<!-- =================================================== -->
+
+<h2>Work around commands that don't understand copies/renames</h2>
+
+<p>When a file or directory is copied or renamed, the Subversion repository
+tracks that history. Unfortunately in Subversion 1.0, the only client
+subcommand which actually takes advantage of this feature is <tt>svn
+log</tt>. A number of other commands (such as <tt>svn diff</tt> and
+<tt>svn cat</tt>) ought to be automatically following rename-history,
+but aren't doing so yet.</p>
+
+<p>In all of these cases, a basic workaround is to use <tt>'svn log
+-v'</tt> to discover the proper path within the older revision.</p>
+
+<p>For example, suppose you copied <tt>/trunk</tt> to
+<tt>/branches/mybranch</tt> in revision 200, and then committed some
+changes to <tt>/branches/mybranch/foo.c</tt> in subsequent revisions.
+Now you'd like to compare revisions 80 and 250 of the file.</p>
+
+<p>If you have a working copy of the branch and run <tt>svn diff
+-r80:250 foo.c</tt>, you'll see an error about
+<tt>/branches/mybranch/foo.c</tt> not existing in revision 80. To
+remedy, you would run <tt>svn log -v</tt> on your branch or file to
+discover that it was named <tt>/trunk/foo.c</tt> prior to revision 200,
+and then compare the two URLs directly:</p>
+
+<pre>
+ $ svn diff http://.../trunk/foo.c@80 \
+ http://.../branches/mybranch/foo.c@200
+</pre>
+
+
+
+<!-- =================================================== -->
+
+<h2>Know when to create branches</h2>
+
+<p>This is a hotly debated question, and it really depends on the
+culture of your software project. Rather than prescribe a universal
+policy, we'll describe three common ones here.</p>
+
+<h3>The Never-Branch system</h3>
+
+<p>(Often used by nascent projects that don't yet have runnable code.)</p>
+
+<ul>
+<li>Users commit their day-to-day work on <tt>/trunk</tt>.</li>
+<li>Occasionally <tt>/trunk</tt> "breaks" (doesn't compile, or fails
+functional tests) when a user begins to commit a series of complicated
+changes.</li>
+</ul>
+
+<p><em>Pros:</em> Very easy policy to follow. New developers have low
+ barrier to entry. Nobody needs to learn how to branch or merge.</p>
+
+<p><em>Cons:</em> Chaotic development, code could be unstable at any
+ time.</p>
+
+<p>A side note: this sort of development is a bit less risky in
+Subversion than in CVS. Because Subversion commits are atomic, it's
+not possible for a checkout or update to receive a "partial" commit
+while somebody else is in the process of committing.</p>
+
+
+<h3>The Always-Branch system</h3>
+
+<p>(Often used by projects that favor heavy management and supervision.)</p>
+
+<ul>
+<li>Each user creates/works on a private branch for <em>every</em> coding task.
+ </li>
+<li>When coding is complete, someone (original coder, peer, or
+ manager) reviews all private branch changes and merges them to
+ <tt>/trunk</tt>.</li>
+</ul>
+
+<p><em>Pros:</em> <tt>/trunk</tt> is guaranteed to be
+ <em>extremely</em> stable at all times. </p>
+
+<p><em>Cons:</em> Coders are artificially isolated from each other,
+ possibly creating more merge conflicts than necessary.
+ Requires users to do lots of extra merging.</p>
+
+
+<h3>The Branch-When-Needed system</h3>
+
+<p>(This is the system used by the Subversion project.)
+
+<ul>
+<li>Users commit their day-to-day work on <tt>/trunk</tt>.</li>
+
+<li>Rule #1: <tt>/trunk</tt> must compile and pass regression tests at
+all times. Committers who violate this rule are publically
+humiliated.</li>
+
+<li>Rule #2: a single commit (changeset) must not be so large
+so as to discourage peer-review.</li>
+
+<li>Rule #3: if rules #1 and #2 come into conflict (i.e. it's
+impossible to make a series of small commits without disrupting the
+trunk), then the user should create a branch and commit a series of
+smaller changesets there. This allows peer-review without disrupting
+the stability of <tt>/trunk</tt>.</li>
+
+</ul>
+
+<p><em>Pros:</em> <tt>/trunk</tt> is guaranteed to be stable at all
+ times. The hassle of branching/merging is somewhat rare.</p>
+
+<p><em>Cons:</em> Adds a bit of burden to users' daily work:
+ they must compile and test before every commit.</p>
+
+
+<!--
+
+
+Mapping CVS tasks to SVN tasks
+==============================
+
+This section is just a re-indexing of topics covered in the book,
+for people who prefer to learn from the "bottom up" rather than "top down".
+It shows some common CVS operations, and then the equivalent SVN operation,
+followed by a link to the book which explains more.
+
+
+* Importing data.
+
+* Checking out a working copy.
+
+* Seeing your changes.
+
+* Undoing your changes.
+
+* Resolving a conflict.
+
+* Adding binary files.
+
+* Activating keyword expansion and/or EOL translation.
+
+
+TAGS:
+
+* Creating a tag from a working copy
+
+* Creating a remote tag
+
+* Seeing all of a project's tags
+
+* Comparing two tags
+
+* Seeing the logs between two tags
+
+* Tweaking a tag
+
+
+BRANCHES:
+
+* Creating a branch and switching to it
+
+* Finding the beginning of a branch
+
+* Merging a branch to trunk, or vice versa
+
+-->
+
+
+</body>
+</html>