[svnbook commit] r1281 - in trunk/src/en: . book
sussman at red-bean.com
Sat May 14 11:17:16 CDT 2005
On May 14, 2005, at 1:06 AM, cmpilato wrote:
> Author: cmpilato
> Date: Sat May 14 01:06:35 2005
> New Revision: 1281
> Add section about peg revisions and tracing complex history.
Nice job, Mike!
I just committed some typo fixes and a comment. But I have a couple
of extra meta-comments:
> + <sect1 id="svn-ch-7-sect-2b">
> + <title>Addressing Historical Ambiguity</title>
This is a fine section title, but I wonder if it's a bit inconsistent
with the rest of chapter 7.
The other section titles in this chapter are exact names of the
feature, e.g. "Properties", rather than "Versioning Metadata",
"Externals definitions" rather than "Building composite working
copies", "Runtime configuration area" rather than "Changing runtime
In other words, the titles are all "Feature name", rather than
"Verbing noun". So I'm wondering if it wouldn't make sense just to
name this section "Peg Revisions"?
> + <screen>
> +$ svn cat -r 1 concept/IDEA
> +subversion/libsvn_client/ra.c:775: (apr_err=20014)
> +svn: Unable to find repository location for 'concept/IDEA' in
> revision 1
> + <para>Of course, in this example, the current
> + <filename>IDEA</filename> file didn't exist yet in revision 1,
> + so Subversion gives an error. The command above is shorthand
> + for a longer notation which explicitly lists a peg revision.
> + The expanded notation is:</para>
> + <screen>
The example(s) you give are excellent, but there's one other thing
I'd love to see in this section: some sort of overview that explains
the *algorithm* that Subversion follows.
You talk about a peg-revision "defining a unique line of history",
and how svn then performs the work on the operative-revision(s). But
I'd love to see this described less in prose, and more as
straightforward algorithm. Something like:
When Subversion sees the syntax "svn subcommand -rX file at PEG", it
* locates the 'file' object in revision PEG (thus pegging a
line of history),
* traces the history line backwards to revision X, and
operates on the older object, whatever its path may be.
I think this sort of top-down algorithmic explanation, if given
before your examples, will make the examples easier to understand.
'Tis my 2 cents.
More information about the svnbook-dev