view release on metacpan or  search on metacpan

src/subversion/doc/user/svn-best-practices.html  view on Meta::CPAN

     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>