[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