Author: hartmannathan
Date: Tue Dec 13 14:03:15 2022
New Revision: 1905961
URL: http://svn.apache.org/viewvc?rev=1905961&view=rev
Log:
In site/staging: Bare Working Copies is now called Pristines On Demand
* site/staging/docs/release-notes/1.15.html:
(#bare-working-copies): Rename to...
(#pristines-on-demand): ...this. Update the text accordingly and try to
improve the description of this feature and its motivation.
Modified:
subversion/site/staging/docs/release-notes/1.15.html
Modified: subversion/site/staging/docs/release-notes/1.15.html
URL:
http://svn.apache.org/viewvc/subversion/site/staging/docs/release-notes/1.15.html?rev=1905961&r1=1905960&r2=1905961&view=diff
==============================================================================
--- subversion/site/staging/docs/release-notes/1.15.html (original)
+++ subversion/site/staging/docs/release-notes/1.15.html Tue Dec 13 14:03:15
2022
@@ -186,57 +186,75 @@ users. We'll cover those in this sectio
title="Link to this section">¶</a>
</h2>
-<div class="h3" id="bare-working-copies">
-<h3>Bare Working Copies
- <a class="sectionlink" href="#bare-working-copies"
+<div class="h3" id="pristines-on-demand">
+<h3>Pristines On Demand
+ <a class="sectionlink" href="#pristines-on-demand"
title="Link to this section">¶</a>
</h3>
-<div class="notice">
-<p><b>The term "Bare Working Copy" is a placeholder for the eventual name of
- this feature.</b></p>
-</div>
-
<p class='todo'>Point to the "User Guide" in <a
href="https://svn.apache.org/repos/asf/subversion/branches/pristines-on-demand-on-mwf/notes/i525/";
><tt>notes/i525/</tt></a>. Regenerate <a href="/docs/i525-user-guide.html"
><tt>/docs/i525-user-guide.html</tt></a> from the source markdown.</p>
+<p>At the user's option, the storage space requirement of a Subversion working
+copy can be reduced by up to 50%.</p>
+
<p>All Subversion working copies require extra storage space in addition to
-the size of the checked out files.</p>
+the size of the checked out files. By default, the total storage space
+required is slightly more than double the size of the checked out files.</p>
-<p>By default, the total storage space required is slightly more than double
-the size of the checked out files. Subversion uses most of that extra space to
-cache each file's BASE revision so that operations such as <tt>diff</tt> and
-<tt>revert</tt> can work offline, and <tt>commit</tt> can send just the
-modified portions of a file to the repository server rather than the whole
-file. This optimises the speed and availability of these operations, on the
-assumption that network throughput to the server is often a bottleneck.</p>
-
-<p>Starting in 1.15, users can check out a bare working copy to cut the
-storage requirement by up to 50%. Instead of caching the BASE revision of all
-files all the time, Subversion will only fetch and cache those of individual
-files when needed, and will eliminate them when no longer needed. The space
-savings come at a tradeoff of requiring a connection to the repository for
-more operations as compared to a normal working copy and may, depending on
-network speeds and file sizes, introduce a perceptible delay when a BASE file
-is downloaded.</p>
-
-<p>This feature is motivated by use cases involving very large versioned files
-that change infrequently, where keeping the cached BASE copy wastes space and
-provides little or no benefit. This feature may also be useful in other
-scenarios, such as where a very fast connection to the server is available,
-the repository is local, available storage space is very limited, etc.</p>
+<p>Subversion uses most of that extra space to cache each file's BASE revision
+("pristine") so that operations such as <tt>diff</tt> and <tt>revert</tt> can
+work offline, and <tt>commit</tt> can send just the modified portions of a
+file to the repository server rather than the whole file. This design
+optimises the speed and availability of these operations on the assumption
+that network connectivity to the repository may be a bottleneck while local
+storage is cheap.</p>
+
+<p>In some use cases, it may be more sensible to fetch one or more pristines
+from the repository server when needed ("on demand"), rather than to cache all
+pristines all the time. Some example use cases:</p>
-<p>To check out a bare working copy:</p>
+<ul>
+ <li>Very large files that change infrequently. In this case, the pristine is
+ usually not needed but takes up space, doubling the storage requirement
+ and providing little or no benefit.</li>
+
+ <li>Working copies on storage-constrained devices with a fast, always-on
+ connection to the repository server. In this case, network bandwidth is
+ more readily available than local storage, inverting the original design
+ assumption that local storage is cheap.</li>
+
+ <li>Working copies on the same device as the repository.</li>
+</ul>
-$ svn checkout --foo --bar $REPO $WC
+<p>As of Subversion 1.15, users can opt for Pristines On Demand at checkout
+time:</p>
-<p>The command to check out a normal working copy is unchanged.</p>
+<pre>
+$ svn checkout --store-pristine=no $REPO $WC
+</pre>
+
+<p>The command to check out a normal working copy is unchanged, but users may
+explicitly write:</p>
+
+<pre>
+$ svn checkout --store-pristine=yes $REPO $WC
+</pre>
+
+<p>When using Pristines On Demand, instead of caching pristines for all files
+all the time, Subversion will only fetch and cache those of individual files
+when needed, and will eliminate them when no longer needed.</p>
+
+<p>Note that the space savings come at a tradeoff of requiring a connection to
+the repository for more operations as compared to a normal working copy and
+may, depending on network speeds and file sizes, introduce a perceptible delay
+when a pristine is downloaded.</p>
<p>The following table lists the Subversion commands that behave differently
-in a bare working copy. For each command, it shows the difference in how that
-command accesses the repository.</p>
+when using Pristines On Demand. For each command, it shows the difference in
+how that command accesses the repository.</p>
<table border="1">
<tr>
@@ -246,7 +264,7 @@ command accesses the repository.</p>
<tr>
<th>Command</th>
<th>Normal</th>
- <th>Bare</th>
+ <th>Pristines On Demand</th>
</tr>
<tr>
@@ -288,10 +306,10 @@ command accesses the repository.</p>
<li><b>Always:</b> Always contacts the repository server.</li>
- <li><b>Hydrate:</b> This operation downloads and keeps the BASE revision for
- each file that has a local content modification (<tt>svn status</tt> shows
- <tt>M</tt> in the 1st column) when its BASE is not already stored in the
- working copy. See notes 1 and 2 below.</li>
+ <li><b>Hydrate:</b> This operation downloads and keeps the pristine for each
+ file that has a local content modification (i.e., when <tt>svn status</tt>
+ shows <tt>M</tt> in the 1st column) when its pristine is not already
+ stored in the working copy. See notes 1 and 2 below.</li>
<li><b>Send-Delta:</b> Sends just the locally modified parts of each file's
content.</li>
@@ -302,18 +320,17 @@ command accesses the repository.</p>
<p>Additional Details:</p>
-<p>Once downloaded, Subversion keeps a file's base locally cached in the
-working copy, so that further operations on the file will not download the
-base from the repository again. It keeps the base in this way until one of
-these operations either restores the file to an unmodified state or detects
-that the file is no longer modified. For example, <tt>commit</tt> and
-<tt>revert</tt> will immediately discard the base of each file they operated
-on, because that file will no longer be locally modified, whereas
-<tt>diff</tt> will discard the base only if it finds there are no
-differences.</p>
+<p>Once downloaded, Subversion keeps a file's pristine locally cached in the
+working copy, so that further operations on the file will not download it from
+the repository again. It keeps the pristine until one of these operations
+either restores the file to an unmodified state or detects that the file is no
+longer modified. For example, <tt>commit</tt> and <tt>revert</tt> will
+immediately discard the pristine of each file they operated on, because that
+file will no longer be locally modified, whereas <tt>diff</tt> will discard
+the pristine only if it finds there are no differences.</p>
<p><b>Note 1:</b> At the beginning of a given operation, Subversion will
-download missing bases of <strong>at least</strong> the files that this
+download missing pristines of <strong>at least</strong> the files that this
particular operation will use. It may download those of other files too, that
this particular operation will not use. For example, in the initial
implementation of this feature, Subversion considers all potential files in
@@ -322,13 +339,13 @@ details of this behaviour are subject to
is released.</p>
<p><b>Note 2:</b> In evaluating differences between a file's working text and
-its base text, Subversion takes into account the "EOL style" and "keywords"
+its BASE text, Subversion takes into account the "EOL style" and "keywords"
settings. (See the <tt>svn:eol-style</tt> and <tt>svn:keywords</tt>
properties.) Just as <tt>svn status</tt> does not show <tt>M</tt> in the first
-column for such differences, neither will these cause the base to be
+column for such differences, neither will these cause the pristine to be
downloaded from the repository.</p>
-</div> <!-- bare-working-copies -->
+</div> <!-- pristines-on-demand -->
<div class="h3" id="streamy-checkouts">
<h3>Streamy Checkouts
