[svnbook] r3876 committed - * src/en/book/ch03-advanced-topics.xml...

svnbook at googlecode.com svnbook at googlecode.com
Tue Jul 5 10:21:33 CDT 2011


Revision: 3876
Author:   cmpilato at gmail.com
Date:     Tue Jul  5 08:21:01 2011
Log:      * src/en/book/ch03-advanced-topics.xml
   Move the 'Peg and Operative Revisions' section to much, much nearer
   the head of this chapter.  Its importance has grown substantially
   since the early days of Subversion.

http://code.google.com/p/svnbook/source/detail?r=3876

Modified:
  /trunk/src/en/book/ch03-advanced-topics.xml

=======================================
--- /trunk/src/en/book/ch03-advanced-topics.xml	Fri Jul  1 07:34:08 2011
+++ /trunk/src/en/book/ch03-advanced-topics.xml	Tue Jul  5 08:21:01 2011
@@ -301,6 +301,357 @@

    </sect1>

+  <!-- =================================================================  
-->
+  <!-- =================================================================  
-->
+  <!-- =================================================================  
-->
+  <sect1 id="svn.advanced.pegrevs">
+    <title>Peg and Operative Revisions</title>
+
+    <para>We copy, move, rename, and completely replace files and
+      directories on our computers all the time.  And your version
+      control system shouldn't get in the way of your doing these
+      things with your version-controlled files and directories,
+      either.  Subversion's file management support is quite
+      liberating, affording almost as much flexibility for versioned
+      files as you'd expect when manipulating your unversioned ones.
+      But that flexibility means that across the lifetime of your
+      repository, a given versioned object might have many paths, and
+      a given path might represent several entirely different
+      versioned objects.  This introduces a certain level of
+      complexity to your interactions with those paths and
+      objects.</para>
+
+    <para>Subversion is pretty smart about noticing when an object's
+      version history includes such <quote>changes of address.</quote>
+      For example, if you ask for the revision history log of a
+      particular file that was renamed last week, Subversion happily
+      provides all those logs—the revision in which the rename
+      itself happened, plus the logs of relevant revisions both before
+      and after that rename.  So, most of the time, you don't even
+      have to think about such things.  But occasionally, Subversion
+      needs your help to clear up ambiguities.</para>
+
+    <para>The simplest example of this occurs when a directory or file
+      is deleted from version control, and then a new directory or
+      file is created with the same name and added to version control.
+      The thing you deleted and the thing you later added aren't the
+      same thing.  They merely happen to have had the same
+      path—<filename>/trunk/object</filename>, for example.
+      What, then, does it mean to ask Subversion about the history of
+      <filename>/trunk/object</filename>?  Are you asking about the
+      thing currently at that location, or the old thing you deleted
+      from that location?  Are you asking about the operations that
+      have happened to <emphasis>all</emphasis> the objects that have
+      ever lived at that path?  Subversion needs a hint about what you
+      really want.</para>
+
+    <para>And thanks to moves, versioned object history can get far
+      more twisted than even that.  For example, you might have a
+      directory named <filename>concept</filename>, containing some
+      nascent software project you've been toying with.  Eventually,
+      though, that project matures to the point that the idea seems to
+      actually have some wings, so you do the unthinkable and decide
+      to give the project a name.
+      <footnote>
+        <para><quote>You're not supposed to name it.  Once you name it,
+          you start getting attached to it.</quote>—Mike
+          Wazowski</para>
+      </footnote>
+      Let's say you called your software Frabnaggilywort.  At this
+      point, it makes sense to rename the directory to reflect the
+      project's new name, so <filename>concept</filename> is renamed
+      to <filename>frabnaggilywort</filename>.  Life goes on,
+      Frabnaggilywort releases a 1.0 version and is downloaded and
+      used daily by hordes of people aiming to improve their
+      lives.</para>
+
+    <para>It's a nice story, really, but it doesn't end there.
+      Entrepreneur that you are, you've already got another think in
+      the tank.  So you make a new directory,
+      <filename>concept</filename>, and the cycle begins again.  In
+      fact, the cycle begins again many times over the years, each
+      time starting with that old <filename>concept</filename>
+      directory, then sometimes seeing that directory renamed as the
+      idea cures, sometimes seeing it deleted when you scrap the idea.
+      Or, to get really sick, maybe you rename
+      <filename>concept</filename> to something else for a while, but
+      later rename the thing back to <filename>concept</filename> for
+      some reason.</para>
+
+    <para>In scenarios like these, attempting to instruct
+      Subversion to work with these reused paths can be a little like
+      instructing a motorist in Chicago's West Suburbs to drive east
+      down Roosevelt Road and turn left onto Main Street.  In a mere
+      20 minutes, you can cross <quote>Main Street</quote> in
+      Wheaton, Glen Ellyn, and Lombard.  And no, they aren't the same
+      street.  Our motorist—and our Subversion—need a
+      little more detail to do the right thing.</para>
+
+    <para>In version 1.1, Subversion introduced a way for you to tell
+      it exactly which Main Street you meant.  It's called the
+      <firstterm>peg revision</firstterm>, and it is provided to
+      Subversion for the sole purpose of identifying a unique line of
+      history.  Because at most, one versioned object may occupy a path
+      at any given time—or, more precisely, in any one
+      revision—the combination of a path and a peg revision is
+      all that is needed to refer to a specific line of history.  Peg
+      revisions are specified to the Subversion command-line client
+      using <firstterm>at syntax</firstterm>, so called because the
+      syntax involves appending an <quote>at sign</quote>
+      (<literal>@</literal>) and the peg revision to the end of the
+      path with which the revision is associated.</para>
+
+    <para>But what of the <option>--revision</option>
+      (<option>-r</option>) of which we've spoken so much in this
+      book?  That revision (or set of revisions) is called the
+      <firstterm>operative revision</firstterm> (or
+      <firstterm>operative revision range</firstterm>).  Once a
+      particular line of history has been identified using a path and
+      peg revision, Subversion performs the requested operation using
+      the operative revision(s).  To map this to our Chicagoland
+      streets analogy, if we are told to go to 606 N. Main Street in
+      Wheaton,
+      <footnote>
+        <para>606 N. Main Street, Wheaton, Illinois, is the home of
+          the Wheaton <emphasis>History</emphasis> Center.  It seemed
+          appropriate….</para>
+      </footnote>
+      we can think of <quote>Main Street</quote> as our path and
+      <quote>Wheaton</quote> as our peg revision.  These two pieces of
+      information identify a unique path that can be traveled (north or
+      south on Main Street), and they keep us from traveling up and
+      down the wrong Main Street in search of our destination.  Now we
+      throw in <quote>606 N.</quote> as our operative revision of
+      sorts, and we know <emphasis>exactly</emphasis> where to
+      go.</para>
+
+    <sidebar>
+      <title>The Peg Revision Algorithm</title>
+
+      <para>The Subversion command-line client performs the peg revision
+        algorithm any time it needs to resolve possible ambiguities in
+        the paths and revisions provided to it.  Here's an example of
+        such an invocation:</para>
+
+      <informalexample>
+        <screen>
+$ svn <replaceable>command</replaceable> -r  
<replaceable>OPERATIVE-REV</replaceable>  
item@<replaceable>PEG-REV</replaceable>
+</screen>
+      </informalexample>
+
+      <para>If <replaceable>OPERATIVE-REV</replaceable> is older than
+        <replaceable>PEG-REV</replaceable>, the algorithm is as
+        follows:</para>
+
+      <orderedlist>
+        <listitem>
+          <para>Locate <replaceable>item</replaceable> in the revision
+            identified by <replaceable>PEG-REV</replaceable>.  There
+            can be only one such object.</para>
+        </listitem>
+        <listitem>
+          <para>Trace the object's history backwards (through any
+            possible renames) to its ancestor in the revision
+            <replaceable>OPERATIVE-REV</replaceable>.</para>
+        </listitem>
+        <listitem>
+          <para>Perform the requested action on that ancestor,
+            wherever it is located, or whatever its name might
+            be or might have been at that time.</para>
+        </listitem>
+      </orderedlist>
+
+      <para>But what if <replaceable>OPERATIVE-REV</replaceable> is
+        <emphasis>younger</emphasis> than
+        <replaceable>PEG-REV</replaceable>?  Well, that adds some
+        complexity to the theoretical problem of locating the path in
+        <replaceable>OPERATIVE-REV</replaceable>, because the path's
+        history could have forked multiple times (thanks to copy
+        operations) between <replaceable>PEG-REV</replaceable> and
+        <replaceable>OPERATIVE-REV</replaceable>.  And that's not
+        all—Subversion doesn't store enough information to
+        performantly trace an object's history forward, anyway.  So
+        the algorithm is a little different:</para>
+
+      <orderedlist>
+        <listitem>
+          <para>Locate <replaceable>item</replaceable> in the revision
+            identified by <replaceable>OPERATIVE-REV</replaceable>.  There
+            can be only one such object.</para>
+        </listitem>
+        <listitem>
+          <para>Trace the object's history backward (through any
+            possible renames) to its ancestor in the revision
+            <replaceable>PEG-REV</replaceable>.</para>
+        </listitem>
+        <listitem>
+          <para>Verify that the object's location (path-wise) in
+            <replaceable>PEG-REV</replaceable> is the same as it is in
+            <replaceable>OPERATIVE-REV</replaceable>.  If that's the
+            case, at least the two locations are known to be
+            directly related, so perform the requested action on the
+            location in <replaceable>OPERATIVE-REV</replaceable>.
+            Otherwise, relatedness was not established, so error out
+            with a loud complaint that no viable location was found.
+            (Someday, we expect that Subversion will be able to handle
+            this usage scenario with more flexibility and
+            grace.)</para>
+        </listitem>
+      </orderedlist>
+
+      <para>Note that even when you don't explicitly supply a peg
+        revision or operative revision, they are still present.  For
+        your convenience, the default peg revision is
+        <literal>BASE</literal> for working copy items and
+        <literal>HEAD</literal> for repository URLs.  And when no
+        operative revision is provided, it defaults to being the same
+        revision as the peg revision.</para>
+
+    </sidebar>
+
+    <para>Say that long ago we created our repository, and in revision 1
+      we added our first <filename>concept</filename> directory, plus an
+      <filename>IDEA</filename> file in that directory talking about
+      the concept.  After several revisions in which real code was
+      added and tweaked, we, in revision 20, renamed this directory to
+      <filename>frabnaggilywort</filename>.  By revision 27, we had a
+      new concept, a new <filename>concept</filename> directory to
+      hold it, and a new <filename>IDEA</filename> file to describe
+      it.  And then five years and thousands of revisions flew by,
+      just like they would in any good romance story.</para>
+
+    <para>Now, years later, we wonder what the
+      <filename>IDEA</filename> file looked like back in revision 1.
+      But Subversion needs to know whether we are asking about how the
+      <emphasis>current</emphasis> file looked back in revision 1, or
+      whether we are asking for the contents of whatever file lived at
+      <filename>concepts/IDEA</filename> in revision 1.  Certainly
+      those questions have different answers, and because of peg
+      revisions, you can ask those questions.  To find out how the
+      current <filename>IDEA</filename> file looked in that old
+      revision, you run:</para>
+
+    <informalexample>
+      <screen>
+$ svn cat -r 1 concept/IDEA
+svn: Unable to find repository location for 'concept/IDEA' in revision 1
+</screen>
+    </informalexample>
+
+    <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 previous command is shorthand
+      for a longer notation which explicitly lists a peg revision.
+      The expanded notation is:</para>
+
+    <informalexample>
+      <screen>
+$ svn cat -r 1 concept/IDEA at BASE
+svn: Unable to find repository location for 'concept/IDEA' in revision 1
+</screen>
+    </informalexample>
+
+    <para>And when executed, it has the expected results.</para>
+
+    <para>The perceptive reader is probably wondering at this point whether
+      the peg revision syntax causes problems for working copy paths
+      or URLs that actually have at signs in them.  After
+      all, how does <command>svn</command> know whether
+      <literal>news at 11</literal> is the name of a directory in my
+      tree or just a syntax for <quote>revision 11 of
+      <filename>news</filename></quote>?  Thankfully, while
+      <command>svn</command> will always assume the latter, there is a
+      trivial workaround.  You need only append an at sign to the
+      end of the path, such as <literal>news at 11@</literal>.
+      <command>svn</command> cares only about the last at sign in
+      the argument, and it is not considered illegal to omit a literal
+      peg revision specifier after that at sign.  This workaround
+      even applies to paths that end in an at sign—you would
+      use <literal>filename@@</literal> to talk about a file named
+      <filename>filename@</filename>.</para>
+
+    <para>Let's ask the other question, then—in revision 1, what
+      were the contents of whatever file occupied the address
+      <filename>concepts/IDEA</filename> at the time?  We'll use an
+      explicit peg revision to help us out.</para>
+
+    <informalexample>
+      <screen>
+$ svn cat concept/IDEA at 1
+The idea behind this project is to come up with a piece of software
+that can frab a naggily wort.  Frabbing naggily worts is tricky
+business, and doing it incorrectly can have serious ramifications, so
+we need to employ over-the-top input validation and data verification
+mechanisms.
+</screen>
+    </informalexample>
+
+    <para>Notice that we didn't provide an operative revision this
+      time.  That's because when no operative revision is specified,
+      Subversion assumes a default operative revision that's the same
+      as the peg revision.</para>
+
+    <para>As you can see, the output from our operation appears to be
+      correct.  The text even mentions frabbing naggily worts, so this
+      is almost certainly the file that describes the software now
+      called Frabnaggilywort.  In fact, we can verify this using the
+      combination of an explicit peg revision and explicit operative
+      revision.  We know that in <literal>HEAD</literal>, the
+      Frabnaggilywort project is located in the
+      <filename>frabnaggilywort</filename> directory.  So we specify
+      that we want to see how the line of history identified in
+      <literal>HEAD</literal> as the path
+      <filename>frabnaggilywort/IDEA</filename> looked in revision
+      1.</para>
+
+    <informalexample>
+      <screen>
+$ svn cat -r 1 frabnaggilywort/IDEA at HEAD
+The idea behind this project is to come up with a piece of software
+that can frab a naggily wort.  Frabbing naggily worts is tricky
+business, and doing it incorrectly can have serious ramifications, so
+we need to employ over-the-top input validation and data verification
+mechanisms.
+</screen>
+    </informalexample>
+
+    <para>And the peg and operative revisions need not be so trivial,
+      either.  For example, say <filename>frabnaggilywort</filename>
+      had been deleted from <literal>HEAD</literal>, but we know it
+      existed in revision 20, and we want to see the diffs for its
+      <filename>IDEA</filename> file between revisions 4 and 10.  We
+      can use the peg revision 20 in conjunction with the URL that
+      would have held Frabnaggilywort's <filename>IDEA</filename> file
+      in revision 20, and then use 4 and 10 as our operative revision
+      range.</para>
+
+    <informalexample>
+      <screen>
+$ svn diff -r 4:10 http://svn.red-bean.com/projects/frabnaggilywort/IDEA@20
+Index: frabnaggilywort/IDEA
+===================================================================
+--- frabnaggilywort/IDEA	(revision 4)
++++ frabnaggilywort/IDEA	(revision 10)
+@@ -1,5 +1,5 @@
+-The idea behind this project is to come up with a piece of software
+-that can frab a naggily wort.  Frabbing naggily worts is tricky
+-business, and doing it incorrectly can have serious ramifications, so
+-we need to employ over-the-top input validation and data verification
+-mechanisms.
++The idea behind this project is to come up with a piece of
++client-server software that can remotely frab a naggily wort.
++Frabbing naggily worts is tricky business, and doing it incorrectly
++can have serious ramifications, so we need to employ over-the-top
++input validation and data verification mechanisms.
+</screen>
+    </informalexample>
+
+    <para>Fortunately, most folks aren't faced with such complex
+      situations.  But when you are, remember that peg revisions are
+      that extra hint Subversion needs to clear up ambiguity.</para>
+
+  </sect1>
+
    <!-- =================================================================  
-->
    <!-- =================================================================  
-->
    <!-- =================================================================  
-->
@@ -3398,357 +3749,6 @@
        subcommands to disable externals definition processing.</para>
    </sect1>

-  <!-- =================================================================  
-->
-  <!-- =================================================================  
-->
-  <!-- =================================================================  
-->
-  <sect1 id="svn.advanced.pegrevs">
-    <title>Peg and Operative Revisions</title>
-
-    <para>We copy, move, rename, and completely replace files and
-      directories on our computers all the time.  And your version
-      control system shouldn't get in the way of your doing these
-      things with your version-controlled files and directories,
-      either.  Subversion's file management support is quite
-      liberating, affording almost as much flexibility for versioned
-      files as you'd expect when manipulating your unversioned ones.
-      But that flexibility means that across the lifetime of your
-      repository, a given versioned object might have many paths, and
-      a given path might represent several entirely different
-      versioned objects.  This introduces a certain level of
-      complexity to your interactions with those paths and
-      objects.</para>
-
-    <para>Subversion is pretty smart about noticing when an object's
-      version history includes such <quote>changes of address.</quote>
-      For example, if you ask for the revision history log of a
-      particular file that was renamed last week, Subversion happily
-      provides all those logs—the revision in which the rename
-      itself happened, plus the logs of relevant revisions both before
-      and after that rename.  So, most of the time, you don't even
-      have to think about such things.  But occasionally, Subversion
-      needs your help to clear up ambiguities.</para>
-
-    <para>The simplest example of this occurs when a directory or file
-      is deleted from version control, and then a new directory or
-      file is created with the same name and added to version control.
-      The thing you deleted and the thing you later added aren't the
-      same thing.  They merely happen to have had the same
-      path—<filename>/trunk/object</filename>, for example.
-      What, then, does it mean to ask Subversion about the history of
-      <filename>/trunk/object</filename>?  Are you asking about the
-      thing currently at that location, or the old thing you deleted
-      from that location?  Are you asking about the operations that
-      have happened to <emphasis>all</emphasis> the objects that have
-      ever lived at that path?  Subversion needs a hint about what you
-      really want.</para>
-
-    <para>And thanks to moves, versioned object history can get far
-      more twisted than even that.  For example, you might have a
-      directory named <filename>concept</filename>, containing some
-      nascent software project you've been toying with.  Eventually,
-      though, that project matures to the point that the idea seems to
-      actually have some wings, so you do the unthinkable and decide
-      to give the project a name.
-      <footnote>
-        <para><quote>You're not supposed to name it.  Once you name it,
-          you start getting attached to it.</quote>—Mike
-          Wazowski</para>
-      </footnote>
-      Let's say you called your software Frabnaggilywort.  At this
-      point, it makes sense to rename the directory to reflect the
-      project's new name, so <filename>concept</filename> is renamed
-      to <filename>frabnaggilywort</filename>.  Life goes on,
-      Frabnaggilywort releases a 1.0 version and is downloaded and
-      used daily by hordes of people aiming to improve their
-      lives.</para>
-
-    <para>It's a nice story, really, but it doesn't end there.
-      Entrepreneur that you are, you've already got another think in
-      the tank.  So you make a new directory,
-      <filename>concept</filename>, and the cycle begins again.  In
-      fact, the cycle begins again many times over the years, each
-      time starting with that old <filename>concept</filename>
-      directory, then sometimes seeing that directory renamed as the
-      idea cures, sometimes seeing it deleted when you scrap the idea.
-      Or, to get really sick, maybe you rename
-      <filename>concept</filename> to something else for a while, but
-      later rename the thing back to <filename>concept</filename> for
-      some reason.</para>
-
-    <para>In scenarios like these, attempting to instruct
-      Subversion to work with these reused paths can be a little like
-      instructing a motorist in Chicago's West Suburbs to drive east
-      down Roosevelt Road and turn left onto Main Street.  In a mere
-      20 minutes, you can cross <quote>Main Street</quote> in
-      Wheaton, Glen Ellyn, and Lombard.  And no, they aren't the same
-      street.  Our motorist—and our Subversion—need a
-      little more detail to do the right thing.</para>
-
-    <para>In version 1.1, Subversion introduced a way for you to tell
-      it exactly which Main Street you meant.  It's called the
-      <firstterm>peg revision</firstterm>, and it is provided to
-      Subversion for the sole purpose of identifying a unique line of
-      history.  Because at most, one versioned object may occupy a path
-      at any given time—or, more precisely, in any one
-      revision—the combination of a path and a peg revision is
-      all that is needed to refer to a specific line of history.  Peg
-      revisions are specified to the Subversion command-line client
-      using <firstterm>at syntax</firstterm>, so called because the
-      syntax involves appending an <quote>at sign</quote>
-      (<literal>@</literal>) and the peg revision to the end of the
-      path with which the revision is associated.</para>
-
-    <para>But what of the <option>--revision</option>
-      (<option>-r</option>) of which we've spoken so much in this
-      book?  That revision (or set of revisions) is called the
-      <firstterm>operative revision</firstterm> (or
-      <firstterm>operative revision range</firstterm>).  Once a
-      particular line of history has been identified using a path and
-      peg revision, Subversion performs the requested operation using
-      the operative revision(s).  To map this to our Chicagoland
-      streets analogy, if we are told to go to 606 N. Main Street in
-      Wheaton,
-      <footnote>
-        <para>606 N. Main Street, Wheaton, Illinois, is the home of
-          the Wheaton <emphasis>History</emphasis> Center.  It seemed
-          appropriate….</para>
-      </footnote>
-      we can think of <quote>Main Street</quote> as our path and
-      <quote>Wheaton</quote> as our peg revision.  These two pieces of
-      information identify a unique path that can be traveled (north or
-      south on Main Street), and they keep us from traveling up and
-      down the wrong Main Street in search of our destination.  Now we
-      throw in <quote>606 N.</quote> as our operative revision of
-      sorts, and we know <emphasis>exactly</emphasis> where to
-      go.</para>
-
-    <sidebar>
-      <title>The Peg Revision Algorithm</title>
-
-      <para>The Subversion command-line client performs the peg revision
-        algorithm any time it needs to resolve possible ambiguities in
-        the paths and revisions provided to it.  Here's an example of
-        such an invocation:</para>
-
-      <informalexample>
-        <screen>
-$ svn <replaceable>command</replaceable> -r  
<replaceable>OPERATIVE-REV</replaceable>  
item@<replaceable>PEG-REV</replaceable>
-</screen>
-      </informalexample>
-
-      <para>If <replaceable>OPERATIVE-REV</replaceable> is older than
-        <replaceable>PEG-REV</replaceable>, the algorithm is as
-        follows:</para>
-
-      <orderedlist>
-        <listitem>
-          <para>Locate <replaceable>item</replaceable> in the revision
-            identified by <replaceable>PEG-REV</replaceable>.  There
-            can be only one such object.</para>
-        </listitem>
-        <listitem>
-          <para>Trace the object's history backwards (through any
-            possible renames) to its ancestor in the revision
-            <replaceable>OPERATIVE-REV</replaceable>.</para>
-        </listitem>
-        <listitem>
-          <para>Perform the requested action on that ancestor,
-            wherever it is located, or whatever its name might
-            be or might have been at that time.</para>
-        </listitem>
-      </orderedlist>
-
-      <para>But what if <replaceable>OPERATIVE-REV</replaceable> is
-        <emphasis>younger</emphasis> than
-        <replaceable>PEG-REV</replaceable>?  Well, that adds some
-        complexity to the theoretical problem of locating the path in
-        <replaceable>OPERATIVE-REV</replaceable>, because the path's
-        history could have forked multiple times (thanks to copy
-        operations) between <replaceable>PEG-REV</replaceable> and
-        <replaceable>OPERATIVE-REV</replaceable>.  And that's not
-        all—Subversion doesn't store enough information to
-        performantly trace an object's history forward, anyway.  So
-        the algorithm is a little different:</para>
-
-      <orderedlist>
-        <listitem>
-          <para>Locate <replaceable>item</replaceable> in the revision
-            identified by <replaceable>OPERATIVE-REV</replaceable>.  There
-            can be only one such object.</para>
-        </listitem>
-        <listitem>
-          <para>Trace the object's history backward (through any
-            possible renames) to its ancestor in the revision
-            <replaceable>PEG-REV</replaceable>.</para>
-        </listitem>
-        <listitem>
-          <para>Verify that the object's location (path-wise) in
-            <replaceable>PEG-REV</replaceable> is the same as it is in
-            <replaceable>OPERATIVE-REV</replaceable>.  If that's the
-            case, at least the two locations are known to be
-            directly related, so perform the requested action on the
-            location in <replaceable>OPERATIVE-REV</replaceable>.
-            Otherwise, relatedness was not established, so error out
-            with a loud complaint that no viable location was found.
-            (Someday, we expect that Subversion will be able to handle
-            this usage scenario with more flexibility and
-            grace.)</para>
-        </listitem>
-      </orderedlist>
-
-      <para>Note that even when you don't explicitly supply a peg
-        revision or operative revision, they are still present.  For
-        your convenience, the default peg revision is
-        <literal>BASE</literal> for working copy items and
-        <literal>HEAD</literal> for repository URLs.  And when no
-        operative revision is provided, it defaults to being the same
-        revision as the peg revision.</para>
-
-    </sidebar>
-
-    <para>Say that long ago we created our repository, and in revision 1
-      we added our first <filename>concept</filename> directory, plus an
-      <filename>IDEA</filename> file in that directory talking about
-      the concept.  After several revisions in which real code was
-      added and tweaked, we, in revision 20, renamed this directory to
-      <filename>frabnaggilywort</filename>.  By revision 27, we had a
-      new concept, a new <filename>concept</filename> directory to
-      hold it, and a new <filename>IDEA</filename> file to describe
-      it.  And then five years and thousands of revisions flew by,
-      just like they would in any good romance story.</para>
-
-    <para>Now, years later, we wonder what the
-      <filename>IDEA</filename> file looked like back in revision 1.
-      But Subversion needs to know whether we are asking about how the
-      <emphasis>current</emphasis> file looked back in revision 1, or
-      whether we are asking for the contents of whatever file lived at
-      <filename>concepts/IDEA</filename> in revision 1.  Certainly
-      those questions have different answers, and because of peg
-      revisions, you can ask those questions.  To find out how the
-      current <filename>IDEA</filename> file looked in that old
-      revision, you run:</para>
-
-    <informalexample>
-      <screen>
-$ svn cat -r 1 concept/IDEA
-svn: Unable to find repository location for 'concept/IDEA' in revision 1
-</screen>
-    </informalexample>
-
-    <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 previous command is shorthand
-      for a longer notation which explicitly lists a peg revision.
-      The expanded notation is:</para>
-
-    <informalexample>
-      <screen>
-$ svn cat -r 1 concept/IDEA at BASE
-svn: Unable to find repository location for 'concept/IDEA' in revision 1
-</screen>
-    </informalexample>
-
-    <para>And when executed, it has the expected results.</para>
-
-    <para>The perceptive reader is probably wondering at this point whether
-      the peg revision syntax causes problems for working copy paths
-      or URLs that actually have at signs in them.  After
-      all, how does <command>svn</command> know whether
-      <literal>news at 11</literal> is the name of a directory in my
-      tree or just a syntax for <quote>revision 11 of
-      <filename>news</filename></quote>?  Thankfully, while
-      <command>svn</command> will always assume the latter, there is a
-      trivial workaround.  You need only append an at sign to the
-      end of the path, such as <literal>news at 11@</literal>.
-      <command>svn</command> cares only about the last at sign in
-      the argument, and it is not considered illegal to omit a literal
-      peg revision specifier after that at sign.  This workaround
-      even applies to paths that end in an at sign—you would
-      use <literal>filename@@</literal> to talk about a file named
-      <filename>filename@</filename>.</para>
-
-    <para>Let's ask the other question, then—in revision 1, what
-      were the contents of whatever file occupied the address
-      <filename>concepts/IDEA</filename> at the time?  We'll use an
-      explicit peg revision to help us out.</para>
-
-    <informalexample>
-      <screen>
-$ svn cat concept/IDEA at 1
-The idea behind this project is to come up with a piece of software
-that can frab a naggily wort.  Frabbing naggily worts is tricky
-business, and doing it incorrectly can have serious ramifications, so
-we need to employ over-the-top input validation and data verification
-mechanisms.
-</screen>
-    </informalexample>
-
-    <para>Notice that we didn't provide an operative revision this
-      time.  That's because when no operative revision is specified,
-      Subversion assumes a default operative revision that's the same
-      as the peg revision.</para>
-
-    <para>As you can see, the output from our operation appears to be
-      correct.  The text even mentions frabbing naggily worts, so this
-      is almost certainly the file that describes the software now
-      called Frabnaggilywort.  In fact, we can verify this using the
-      combination of an explicit peg revision and explicit operative
-      revision.  We know that in <literal>HEAD</literal>, the
-      Frabnaggilywort project is located in the
-      <filename>frabnaggilywort</filename> directory.  So we specify
-      that we want to see how the line of history identified in
-      <literal>HEAD</literal> as the path
-      <filename>frabnaggilywort/IDEA</filename> looked in revision
-      1.</para>
-
-    <informalexample>
-      <screen>
-$ svn cat -r 1 frabnaggilywort/IDEA at HEAD
-The idea behind this project is to come up with a piece of software
-that can frab a naggily wort.  Frabbing naggily worts is tricky
-business, and doing it incorrectly can have serious ramifications, so
-we need to employ over-the-top input validation and data verification
-mechanisms.
-</screen>
-    </informalexample>
-
-    <para>And the peg and operative revisions need not be so trivial,
-      either.  For example, say <filename>frabnaggilywort</filename>
-      had been deleted from <literal>HEAD</literal>, but we know it
-      existed in revision 20, and we want to see the diffs for its
-      <filename>IDEA</filename> file between revisions 4 and 10.  We
-      can use the peg revision 20 in conjunction with the URL that
-      would have held Frabnaggilywort's <filename>IDEA</filename> file
-      in revision 20, and then use 4 and 10 as our operative revision
-      range.</para>
-
-    <informalexample>
-      <screen>
-$ svn diff -r 4:10 http://svn.red-bean.com/projects/frabnaggilywort/IDEA@20
-Index: frabnaggilywort/IDEA
-===================================================================
---- frabnaggilywort/IDEA	(revision 4)
-+++ frabnaggilywort/IDEA	(revision 10)
-@@ -1,5 +1,5 @@
--The idea behind this project is to come up with a piece of software
--that can frab a naggily wort.  Frabbing naggily worts is tricky
--business, and doing it incorrectly can have serious ramifications, so
--we need to employ over-the-top input validation and data verification
--mechanisms.
-+The idea behind this project is to come up with a piece of
-+client-server software that can remotely frab a naggily wort.
-+Frabbing naggily worts is tricky business, and doing it incorrectly
-+can have serious ramifications, so we need to employ over-the-top
-+input validation and data verification mechanisms.
-</screen>
-    </informalexample>
-
-    <para>Fortunately, most folks aren't faced with such complex
-      situations.  But when you are, remember that peg revisions are
-      that extra hint Subversion needs to clear up ambiguity.</para>
-
-  </sect1>
-
    <!-- =================================================================  
-->
    <!-- =================================================================  
-->
    <!-- =================================================================  
-->




More information about the svnbook-dev mailing list