[svnbook commit] r2606 - trunk/src/en/book

cmpilato noreply at red-bean.com
Thu Jan 4 23:11:56 CST 2007


Author: cmpilato
Date: Thu Jan  4 23:11:56 2007
New Revision: 2606

Modified:
   trunk/src/en/book/ch-advanced-topics.xml
   trunk/src/en/book/ch-basic-usage.xml

Log:
* src/en/book/ch-basic-usage.xml
  Move the chatter about revision keywords and dates from here...

* src/en/book/ch-advanced-topics.xml
  ...to here.


Modified: trunk/src/en/book/ch-advanced-topics.xml
==============================================================================
--- trunk/src/en/book/ch-advanced-topics.xml	(original)
+++ trunk/src/en/book/ch-advanced-topics.xml	Thu Jan  4 23:11:56 2007
@@ -31,6 +31,225 @@
   <!-- ================================================================= -->
   <!-- ================================================================= -->
   <!-- ================================================================= -->
+  <sect1 id="svn.tour.revs.specifiers">
+    <title>Revision Specifiers</title>
+
+    <para>As we saw in <xref linkend="svn.tour.revs" />, revision
+      numbers in Subversion are pretty straightforward—integers
+      that keep getting larger as you commit more changes to your
+      versioned data.  Still, it doesn't take long before you can no
+      longer remember exactly what happened in each and every
+      revision.  Fortunately, the typical Subversion workflow doesn't
+      often demand that you supply arbitrary revisions to the
+      Subversion operations you perform.  For operations that
+      <emphasis>do</emphasis> require a revision specifier, you
+      generally supply a revision number that you saw in a commit
+      email, in the output of some other Subversion operation, or in
+      some other context that would yield meaning to that particular
+      number.</para>
+
+    <para>But occasionally, you need to pinpoint a moment in time for
+      which you don't already have a revision number memorized or
+      handy.  So besides the integer revision numbers,
+      <command>svn</command> allows as input some additional forms of
+      revision specifiers—revision keywords, and revision
+      dates.</para>
+
+    <note>
+      <para>The various forms of Subversion revision specifiers can be
+        mixed and matched when used to specify revision ranges.  For
+        example, you can use <option>-r
+        <replaceable>REV1</replaceable>:<replaceable>REV2</replaceable></option>
+        where <replaceable>REV1</replaceable> is a revision keyword
+        and <replaceable>REV2</replaceable> is a revision number, or
+        where <replaceable>REV1</replaceable> is a date and
+        <replaceable>REV2</replaceable> is a revision keyword, and so
+        on.  The individual revision specifiers are independently
+        evaluated, so you can put whatever you want on the opposite
+        sides of that colon.</para>
+    </note>
+    
+    <!-- =============================================================== -->
+    <sect2 id="svn.tour.revs.keywords">
+      <title>Revision Keywords</title>
+      
+      <para>The Subversion client understands a number of
+        <firstterm>revision keywords</firstterm>.  These keywords can
+        be used instead of integer arguments to the
+        <option>--revision</option> switch, and are resolved into
+        specific revision numbers by Subversion:</para>
+
+      <variablelist>
+        
+        <varlistentry>
+          <term>HEAD</term>
+          <listitem>
+            <para>The latest (or <quote>youngest</quote>) revision in
+              the repository.</para>
+          </listitem>
+        </varlistentry>
+        
+        <varlistentry>
+          <term>BASE</term>
+          <listitem>
+            <para>The revision number of an item in a working copy.
+              If the item has been locally modified, the <quote>BASE
+              version</quote> refers to the way the item appears
+              without those local modifications.</para>
+          </listitem>
+        </varlistentry>
+        
+        <varlistentry>
+          <term>COMMITTED</term>
+          <listitem>
+            <para>The most recent revision prior to, or equal to,
+              <literal>BASE</literal>, in which an item changed.</para>
+          </listitem>
+        </varlistentry>
+        
+        <varlistentry>
+          <term>PREV</term>
+          <listitem>
+            <para>The revision immediately <emphasis>before</emphasis>
+              the last revision in which an item changed.
+              Technically, this boils down to
+              <literal>COMMITTED</literal>-1.</para>
+          </listitem>
+        </varlistentry>
+        
+      </variablelist>
+
+      <para>As can be derived from their descriptions, the
+        <literal>PREV</literal>, <literal>BASE</literal>, and
+        <literal>COMMITTED</literal> revision keywords are used only
+        when referring to a working copy path—they don't apply
+        to repository URLs.  <literal>HEAD</literal>, on the other
+        hand, can be used in conjuction with both of these path
+        types.</para>
+      
+      <para>Here are some examples of revision keywords in action.
+        Don't worry if the commands don't make sense yet; we'll be
+        explaining these commands as we go through the chapter:</para>
+      
+      <screen>
+$ svn diff -r PREV:COMMITTED foo.c
+# shows the last change committed to foo.c
+
+$ svn log -r HEAD
+# shows log message for the latest repository commit
+
+$ svn diff -r HEAD
+# compares your working copy (with all of its local changes) to the
+# latest version of that tree in the repository
+
+$ svn diff -r BASE:HEAD foo.c
+# compares the unmodified version of foo.c with the latest version of
+# foo.c in the repository
+
+$ svn log -r BASE:HEAD
+# shows all commit logs for the current versioned directory since you
+# last updated
+
+$ svn update -r PREV foo.c
+# rewinds the last change on foo.c, decreasing foo.c's working revision
+
+$ svn diff -r BASE:14 foo.c
+# compares the unmodified version of foo.c with the way foo.c looked
+# in revision 14
+</screen>
+      
+    </sect2>
+    
+    <!-- =============================================================== -->
+    <sect2 id="svn.tour.revs.dates">
+      <title>Revision Dates</title>
+      
+      <para>Revision numbers reveal nothing about the world outside
+        the version control system, but sometimes you need to
+        correlate a moment in real time with a moment in version
+        history.  To facilitate this, the <option>--revision</option>
+        option can also accept as input date specifiers wrapped in
+        curly braces (<literal>{</literal> and <literal>}</literal>).
+        Subversion accepts the standard ISO-8601 date and time
+        formats, plus a few others.  Here are some examples.
+        (Remember to use quotes around any date that contains
+        spaces.)</para>
+
+      <screen>
+$ svn checkout -r {2002-02-17}
+$ svn checkout -r {15:30}
+$ svn checkout -r {15:30:00.200000}
+$ svn checkout -r {"2002-02-17 15:30"}
+$ svn checkout -r {"2002-02-17 15:30 +0230"}
+$ svn checkout -r {2002-02-17T15:30}
+$ svn checkout -r {2002-02-17T15:30Z}
+$ svn checkout -r {2002-02-17T15:30-04:00}
+$ svn checkout -r {20020217T1530}
+$ svn checkout -r {20020217T1530Z}
+$ svn checkout -r {20020217T1530-0500}
+…
+</screen>
+      
+      <para>When you specify a date, Subversion resolves that date to
+        the most recent revision of the repository as of that date,
+        and then continues to operate against that resolved revision
+        number:</para>
+        
+      <screen>
+$ svn log -r {2002-11-28}
+------------------------------------------------------------------------
+r12 | ira | 2002-11-27 12:31:51 -0600 (Wed, 27 Nov 2002) | 6 lines
+…
+</screen>
+        
+      <sidebar>
+        <title>Is Subversion a Day Early?</title>
+        
+        <para>If you specify a single date as a revision without
+          specifying a time of day (for example
+          <literal>2002-11-27</literal>), you may think that Subversion
+          should give you the last revision that took place on the
+          27th of November.  Instead, you'll get back a revision from
+          the 26th, or even earlier.  Remember that Subversion will
+          find the <emphasis>most recent revision of the
+          repository</emphasis> as of the date you give.  If you give
+          a date without a timestamp, like
+          <literal>2002-11-27</literal>, Subversion assumes a time of
+          00:00:00, so looking for the most recent revision won't
+          return anything on the day of the 27th.</para>
+
+        <para>If you want to include the 27th in your search, you can
+          either specify the 27th with the time (<literal>{"2002-11-27
+          23:59"}</literal>), or just specify the next day
+          (<literal>{2002-11-28}</literal>).</para>
+        
+      </sidebar>
+      
+      <para>You can also use a range of dates.  Subversion will find
+        all revisions between both dates, inclusive:</para>
+      
+      <screen>
+$ svn log -r {2002-11-20}:{2002-11-29}
+…
+</screen>
+        
+      <warning>
+        <para>Since the timestamp of a revision is stored as an
+          unversioned, modifiable property of the revision (see <xref
+          linkend="svn.advanced.props" />, revision timestamps can be
+          changed to represent complete falsifications of true
+          chronology, or even removed altogether.  This will wreak
+          havoc on the internal date-to-revision conversion that
+          Subversion performs.</para>
+      </warning>
+        
+    </sect2>
+      
+  </sect1>
+
+  <!-- ================================================================= -->
+  <!-- ================================================================= -->
+  <!-- ================================================================= -->
   <sect1 id="svn.advanced.pegrevs">
     <title>Peg and Operative Revisions</title>
 

Modified: trunk/src/en/book/ch-basic-usage.xml
==============================================================================
--- trunk/src/en/book/ch-basic-usage.xml	(original)
+++ trunk/src/en/book/ch-basic-usage.xml	Thu Jan  4 23:11:56 2007
@@ -54,239 +54,65 @@
   <!-- ================================================================= -->
   <!-- ================================================================= -->
   <sect1 id="svn.tour.revs">
-    <title>Revisions: Numbers, Keywords, and Dates, Oh My!</title>
+    <title>Time Travel with Subversion</title>
 
-    <para>Before we go on, you should know a bit about how to identify
-      a particular revision in your repository.  As you learned in
-      <xref linkend="svn.basic.in-action.revs"/>, a revision is a
-      <quote>snapshot</quote> of the repository at a particular moment
-      in time.  As you continue to commit and grow your repository,
-      you need a mechanism for identifying these snapshots.</para>
-
-    <para>You specify these revisions by using the
-      <option>--revision</option> (<option>-r</option>) switch plus
-      the revision you want (<command>svn --revision REV</command>) or
-      you can specify a range by separating two revisions with a colon
-      (<command>svn --revision REV1:REV2</command>).  And Subversion
-      lets you refer to these revisions by number, keyword, or
-      date.</para>
-    
-    <!-- =============================================================== -->
-    <sect2 id="svn.tour.revs.numbers">
-      <title>Revision Numbers</title>
-      
-      <para>When you create a new Subversion repository, it begins its
-        life at revision zero and each successive commit increases the
-        revision number by one.  After your commit completes, the
-        Subversion client informs you of the new revision
-        number:</para>
+    <para>As discussed in <xref linkend="svn.basic.in-action.revs"/>,
+      a revision is a <quote>snapshot</quote> of the repository at a
+      particular moment in time.  But the thing that makes
+      Subversion—or any other version control
+      system—useful is not that it keeps all the versions of
+      your files and directories over time.  It's that you can
+      actually <emphasis>do something</emphasis> with those older
+      versions!  And to do this sort of time travelling, you need a
+      mechanism for identifying revision snapshots.</para>
+
+    <para>Revision numbers in Subversion are pretty
+      straightforward—just monotonically increasing integers.
+      When you create a new Subversion repository, it begins its life
+      at revision 0 and each successive commit increases the revision
+      number by one.  Subversion doesn't try to hide these
+      numbers—they are a part of the interface you have into the
+      history of your versioned data.  For example, after you perform
+      a commit, the Subversion client informs you of the new revision
+      number:</para>
       
-      <screen>
+    <screen>
 $ svn commit --message "Corrected number of cheese slices."
 Sending        sandwich.txt
 Transmitting file data .
 Committed revision 3.
 </screen>
 
-      <para>If at any point in the future you want to refer to that
-        revision (we'll see how and why we might want to do that later
-        in this chapter), you can refer to it as
-        <quote>3</quote>.</para>
-
-    </sect2>
-    
-    <!-- =============================================================== -->
-    <sect2 id="svn.tour.revs.keywords">
-      <title>Revision Keywords</title>
-      
-      <para>The Subversion client understands a number of
-        <firstterm>revision keywords</firstterm>.  These keywords
-        can be used instead of integer arguments to the
-        <option>--revision</option> switch, and are resolved into
-        specific revision numbers by Subversion:</para>
-
-      <note>
-        <para>Each directory in your working copy contains an
-          administrative subdirectory called
-          <filename>.svn</filename>.  For every file in a directory,
-          Subversion keeps a copy of each file in the administrative
-          area.  This copy is an unmodified (no keyword expansion, no
-          end-of-line translation, no nothing) copy of the file as it
-          existed in the last revision (called the <quote>BASE</quote>
-          revision) that you updated it to in your working copy.  We
-          refer to this file as the <firstterm>pristine
-          copy</firstterm> or <firstterm>text-base</firstterm> version
-          of your file, and it's always an exact byte-for-byte copy of
-          the file as it exists in the repository.</para> 
-        </note>
-      
-      <variablelist>
-        
-        <varlistentry>
-          <term>HEAD</term>
-          <listitem>
-            <para>The latest (or <quote>youngest</quote>) revision in
-              the repository.</para>
-          </listitem>
-        </varlistentry>
-        
-        <varlistentry>
-          <term>BASE</term>
-          <listitem>
-            <para>The revision number of an item in a working copy.
-              If the item has been locally modified, the <quote>BASE
-              version</quote> refers to the way the item appears
-              without those local modifications.</para>
-          </listitem>
-        </varlistentry>
-        
-        <varlistentry>
-          <term>COMMITTED</term>
-          <listitem>
-            <para>The most recent revision prior to, or equal to,
-              <literal>BASE</literal>, in which an item changed.</para>
-          </listitem>
-        </varlistentry>
-        
-        <varlistentry>
-          <term>PREV</term>
-          <listitem>
-            <para>The revision immediately <emphasis>before</emphasis>
-              the last revision in which an item changed.
-              (Technically, <literal>COMMITTED</literal> - 1.)</para>
-          </listitem>
-        </varlistentry>
-        
-      </variablelist>
-
-      <note>
-        <para><literal>PREV</literal>, <literal>BASE</literal>, and
-          <literal>COMMITTED</literal> can be used to refer to local
-          paths, but not to URLs.</para>
-      </note>
-      
-      <para>Here are some examples of revision keywords in action.
-        Don't worry if the commands don't make sense yet; we'll be
-        explaining these commands as we go through the chapter:</para>
-      
-      <screen>
-$ svn diff --revision PREV:COMMITTED foo.c
-# shows the last change committed to foo.c
-
-$ svn log --revision HEAD
-# shows log message for the latest repository commit
-
-$ svn diff --revision HEAD
-# compares your working file (with local changes) to the latest version
-# in the repository
-
-$ svn diff --revision BASE:HEAD foo.c
-# compares your <quote>pristine</quote> foo.c (no local changes) with the 
-# latest version in the repository
-
-$ svn log --revision BASE:HEAD
-# shows all commit logs since you last updated
-
-$ svn update --revision PREV foo.c
-# rewinds the last change on foo.c
-# (foo.c's working revision is decreased)
-</screen>
-      
-      <para>These keywords allow you to perform many common (and
-        helpful) operations without having to look up specific
-        revision numbers or remember the exact revision of your
-        working copy.</para>
-      
-    </sect2>
-    
-    <!-- =============================================================== -->
-    <sect2 id="svn.tour.revs.dates">
-      <title>Revision Dates</title>
-      
-      <para>Anywhere that you specify a revision number or revision
-        keyword, you can also specify a date
-        inside curly braces <quote>{}</quote>.  You can even access
-        a range of changes in the repository using both dates and
-        revisions together!</para>
-      
-      <para>Here are examples of the date formats that Subversion
-        accepts.  Remember to use quotes around any date that contains
-        spaces.</para>
-
-      <screen>
-$ svn checkout --revision {2002-02-17}
-$ svn checkout --revision {15:30}
-$ svn checkout --revision {15:30:00.200000}
-$ svn checkout --revision {"2002-02-17 15:30"}
-$ svn checkout --revision {"2002-02-17 15:30 +0230"}
-$ svn checkout --revision {2002-02-17T15:30}
-$ svn checkout --revision {2002-02-17T15:30Z}
-$ svn checkout --revision {2002-02-17T15:30-04:00}
-$ svn checkout --revision {20020217T1530}
-$ svn checkout --revision {20020217T1530Z}
-$ svn checkout --revision {20020217T1530-0500}
-…
-</screen>
-      
-      <para>When you specify a date as a revision, Subversion finds
-        the most recent revision of the repository as of that
-        date:</para>
-        
-      <screen>
-$ svn log --revision {2002-11-28}
-------------------------------------------------------------------------
-r12 | ira | 2002-11-27 12:31:51 -0600 (Wed, 27 Nov 2002) | 6 lines
-…
-</screen>
-        
-      <sidebar>
-        <title>Is Subversion a Day Early?</title>
-        
-        <para>If you specify a single date as a revision without
-          specifying a time of day (for example
-          <literal>2002-11-27</literal>), you may think that Subversion
-          should give you the last revision that took place on the
-          27th of November.  Instead, you'll get back a revision from
-          the 26th, or even earlier.  Remember that Subversion will
-          find the <emphasis>most recent revision of the
-          repository</emphasis> as of the date you give.  If you give
-          a date without a timestamp, like
-          <literal>2002-11-27</literal>, Subversion assumes a time of
-          00:00:00, so looking for the most recent revision won't
-          return anything on the day of the 27th.</para>
-
-        <para>If you want to include the 27th in your search, you can
-          either specify the 27th with the time (<literal>{"2002-11-27
-          23:59"}</literal>), or just specify the next day
-          (<literal>{2002-11-28}</literal>).</para>
-        
-      </sidebar>
-      
-      <para>You can also use a range of dates.  Subversion will find
-        all revisions between both dates, inclusive:</para>
-      
-      <screen>
-$ svn log --revision {2002-11-20}:{2002-11-29}
-…
-</screen>
-        
-      <para>As we pointed out, you can also mix dates and revisions:</para>
-      
-      <screen>
-$ svn log --revision {2002-11-20}:4040
-</screen>
+    <para>If at any point in the future you want to refer to that
+      revision, you can do so by specifying it as
+      <literal>3</literal>.  We'll discover some reasons why you might
+      want to do that later in this chapter.</para>
+
+    <para>The <command>svn</command> command-line client provides a
+      pair of options for specifying the revisions you wish to operate
+      on.  The most common of these is the <option>--revision</option>
+      (<option>-r</option>), which accepts as a parameter either a
+      single revision specifier (<option>-r
+      <replaceable>REV</replaceable></option>), or a pair of them
+      separated by a colon (<option>-r
+      <replaceable>REV1</replaceable>:<replaceable>REV2</replaceable></option>).
+      This latter format is used to describe a <firstterm>revision
+      range</firstterm>, useful for commands that compare two revision
+      snapshots or operate on every revision between two specified
+      extremes, inclusively.</para>
+
+    <para>Subversion 1.4 introduced a second option for specifying
+      revision ranges, the <option>--change</option>
+      (<option>-c</option>) option.  This is basically just a shortcut
+      for specifying a range of revisions whose boundaries are
+      sequential integers.  In other words, using <option>-c
+      <replaceable>REV</replaceable></option> is the same thing as
+      using <option>-r
+      <replaceable>REV</replaceable>-1:<replaceable>REV</replaceable></option>.
+      And you can trivially reverse the implied range, too, by putting
+      a dash in front of the revision number, as in <option>-c
+      -<replaceable>REV</replaceable></option>.</para>
 
-      <para>Users should be aware of a subtlety that can become quite
-        a stumbling-block when dealing with dates in Subversion.  Since
-        the timestamp of a revision is stored as a property of the
-        revision—an unversioned, modifiable
-        property—revision timestamps can be changed to represent
-        complete falsifications of true chronology, or even removed
-        altogether.  This will wreak havoc on the internal
-        date-to-revision conversion that Subversion performs.</para>
-        
-    </sect2>
-      
   </sect1>
 
   <!-- ================================================================= -->




More information about the svnbook-dev mailing list