Author: hartmannathan
Date: Tue Feb 25 05:04:58 2025
New Revision: 1924034
URL: http://svn.apache.org/viewvc?rev=1924034&view=rev
Log:
In staging, 1.15 release notes: Reorganize/expand #pristines-on-demand section
* 1.15.html
(#pristines-on-demand): Split into several subsections to better organize
the presentation. The order of several paragraphs is changed to fit the new
subsections. Adding an example 'svn info' output to show pristine storage
type. Various other tweaks to the text.
(#pristines-on-demand-background,
#pristines-on-demand-tradeoffs,
#pristines-on-demand-checkout,
#pristines-on-demand-info,
#pristines-on-demand-repo-access,
#pristines-on-demand-notes,
#pristines-on-demand-future): The new subsections.
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=1924034&r1=1924033&r2=1924034&view=diff
==============================================================================
--- subversion/site/staging/docs/release-notes/1.15.html (original)
+++ subversion/site/staging/docs/release-notes/1.15.html Tue Feb 25 05:04:58
2025
@@ -244,68 +244,150 @@ users. We'll cover those in this sectio
title="Link to this section">¶</a>
</h3>
-<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. By default, the total storage space
-required is slightly more than double the size of the checked out files.</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>The space savings are achieved by reducing or eliminating cached content in
+the working copy administrative directory (<tt>.svn</tt>) at the potential
+cost of additional communication with the repository server.</p>
+
+<div class="h4" id="pristines-on-demand-background">
+<h4>Background
+ <a class="sectionlink" href="#pristines-on-demand-background"
+ title="Link to this section">¶</a>
+</h4>
+
+<p>All Subversion working copies require extra storage space for the working
+copy administrative directory (<tt>.svn</tt>). By default, the storage space
+required for this administrative directory is slightly more than the total
+size of the checked out files. Subversion uses most of that extra space to
+cache a copy of 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.</p>
+
+<p>This design optimises the speed and availability of these operations on the
+assumption that network connectivity to the repository may be a bottleneck (or
+unavailable at times) while local storage is assumed to be inexpensive.</p>
+
+<p>However, in some use cases, it may be more sensible to fetch pristines from
+the repository server only when needed ("on demand"), rather than to cache all
+pristines all the time. Some example use cases:</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>Very large files that change infrequently. In this case, the pristine
+ is usually not needed but takes up space, doubling the storage requirement
+ while 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
+ 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>
+ assumption that local storage is inexpensive.</li>
<li>Working copies on the same device as the repository.</li>
</ul>
+<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>
+
+</div> <!-- pristines-on-demand-background -->
+
+<div class="h4" id="pristines-on-demand-tradeoffs">
+<h4>Tradeoffs
+ <a class="sectionlink" href="#pristines-on-demand-tradeoffs"
+ title="Link to this section">¶</a>
+</h4>
+
+<p>The space savings come with some tradeoffs:</p>
+
+<p>A Subversion 1.15 or newer client is required to operate on the working
+copy. The working copy cannot be used interchangeably with Subversion 1.8
+through 1.14 clients, as these will report an error.</p>
+
+<p>A connection to the repository server is required for more operations as
+compared to a fully-cached working copy. Depending on network speeds and file
+sizes, the additional network communications may introduce a perceptible delay
+when a pristine is downloaded.</p>
+
+</div> <!-- pristines-on-demand-tradeoffs -->
+
+<div class="h4" id="pristines-on-demand-checkout">
+<h4>Checking Out a Pristines On Demand Working Copy
+ <a class="sectionlink" href="#pristines-on-demand-checkout"
+ title="Link to this section">¶</a>
+</h4>
+
<p>As of Subversion 1.15, users can opt for Pristines On Demand at checkout
-time. This applies to the entire working copy:</p>
+time by giving the <tt>--store-pristine=no</tt> option. This applies to the
+entire working copy:</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 <tt>yes</tt>:</p>
+<p>Otherwise, the default is to check out a normal, fully cached working copy:
+</p>
+
+<pre>
+$ svn checkout $REPO $WC
+</pre>
+
+<p>Users may also write <tt>--store-pristine=yes</tt> to explicitly request a
+a normal, fully cached working copy. This may be useful in scripting
+scenarios:</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>
+</div> <!-- pristines-on-demand-checkout -->
-<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>
+<div class="h4" id="pristines-on-demand-info">
+<h4>Examining the Working Copy Pristines Type
+ <a class="sectionlink" href="#pristines-on-demand-info"
+ title="Link to this section">¶</a>
+</h4>
+
+<p>Users can check whether a working copy uses Pristines On Demand with the
+<tt>svn info</tt> command. This command shows several fields which are new
+in Subversion 1.15, shown in <b>bold</b> here:</p>
+
+<pre>
+$ svn info
+Path: .
+Working Copy Root Path: /ramdrive/svn-trunk
+<span style="font-weight: bold">Working Copy Compatible With Version: 1.15
+Working Copy Format: 32
+Working Copy Store Pristine: no</span>
+URL: https://svn.apache.org/repos/asf/subversion/trunk
+Relative URL: ^/subversion/trunk
+Repository Root: https://svn.apache.org/repos/asf
+Repository UUID: 13f79535-47bb-0310-9956-ffa450edef68
+Revision: 1924024
+Node Kind: directory
+Schedule: normal
+Last Changed Author: dsahlberg
+Last Changed Rev: 1923965
+Last Changed Date: 2025-02-21 11:08:37 -0500 (Fri, 21 Feb 2025)
+</pre>
+
+<p>The relevant one is <tt>Working Copy Store Pristine</tt>. This shows
+<tt>no</tt> when using Pristines On Demand (coinciding with the
+<tt>--store-pristine=no</tt> command line switch), <tt>yes</tt> when using a
+normal, fully cached working copy (coinciding with
+<tt>--store-pristine=yes</tt>).</p>
+
+</div> <!-- pristines-on-demand-info -->
+
+<div class="h4" id="pristines-on-demand-repo-access">
+<h4>Repository Access Comparison
+ <a class="sectionlink" href="#pristines-on-demand-repo-access"
+ title="Link to this section">¶</a>
+</h4>
<p>The following table lists the Subversion commands that behave differently
-when using Pristines On Demand. For each command, it shows the difference in
+when using Pristines On Demand. For each command, it shows the difference in
how that command accesses the repository.</p>
<table border="1">
@@ -361,7 +443,7 @@ how that command accesses the repository
<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>
+ 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>
@@ -370,21 +452,28 @@ how that command accesses the repository
file.</li>
</ul>
-<p>Additional Details:</p>
+</div> <!-- pristines-on-demand-repo-access -->
+
+<div class="h4" id="pristines-on-demand-notes">
+<h4>Additional Details
+ <a class="sectionlink" href="#pristines-on-demand-notes"
+ title="Link to this section">¶</a>
+</h4>
<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>
+working copy administrative directory so that further operations on the file
+will not download it from the repository again. Subversion keeps the pristine
+until an operation 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 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
+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
the smallest subtree that spans all the target files of the operation. The
details of this behaviour are subject to change before and after the feature
@@ -392,20 +481,33 @@ 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"
-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 pristine to be
+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 pristine to be
downloaded from the repository.</p>
-<p>Limitations and Future Possibilities:</p>
+</div> <!-- pristines-on-demand-notes -->
+
+<div class="h4" id="pristines-on-demand-future">
+<h4>Limitations and Future Possibilities
+ <a class="sectionlink" href="#pristines-on-demand-future"
+ title="Link to this section">¶</a>
+</h4>
<p>Currently, this feature applies to an entire working copy. That is, either
all working files have their pristines cached (the default) or all working
-files use pristines on demand (<tt>--store-pristine=no</tt>). In the future,
+files use pristines on demand (<tt>--store-pristine=no</tt>). In the future,
this feature may be enhanced to give users more granular control, such as by
allowing the <tt>--store-pristine</tt> switch to apply to individual files.
</p>
+<p class='todo'>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>
+
+</div> <!-- pristines-on-demand-future -->
+
</div> <!-- pristines-on-demand -->
<div class="h3" id="multi-wc-format">
