[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