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

cmpilato noreply at red-bean.com
Fri Jan 5 00:54:05 CST 2007


Author: cmpilato
Date: Fri Jan  5 00:54:04 2007
New Revision: 2611

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

Log:
* src/en/book/ch-advanced-topics.xml
  (Where's $GlobalRev$): Rework Ben's sidebar a bit, losing the "why
    not" and focusing on the "how to".


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	Fri Jan  5 00:54:04 2007
@@ -1814,33 +1814,29 @@
     <sidebar>
       <title>Where's $GlobalRev$?</title>
 
-      <para>New users are often confused by how
-        the <literal>$Rev$</literal> keyword works.  Since the
-        repository has a single, globally increasing revision number,
-        many people assume that this value will be reflected by
-        the <literal>$Rev$</literal> keyword.  Not so!  The value of
-        this keyword is only expanded to show the last revision in
-        which the file changed.  While files don't really have their
-        own revision numbers, this keyword value still represents a
-        unique version of the file.  It's only updated when the file
-        itself changes.</para>
-
-      <para>A common reaction to this news is frustration: <quote>Why
-          isn't there a <literal>$GlobalRev$</literal> keyword then?
-          I want to include the global revision in my file as an
-          identifier for my whole project.</quote> The answer is in
-          two parts.  First, a global-revision keyword doesn't exist
-          because it would be too inefficient to implement.  After
-          every single <command>svn update</command>, the client would
-          have to scan the entire working copy, potentially looking to
-          expand the keyword in every file!  Second,
-          it <emphasis>is</emphasis> possible to embed project-wide
-          revision numbers into a file.
-          The <command>svnversion</command> tool was designed just for
-          this purpose.  Have your build-system run this tool on your
-          working copy, and embed the resulting value in your file.
-          More information on <command>svnversion</command> is
-          available at <xref linkend="svn.ref.svnversion"/>.</para>
+      <para>New users are often confused by how the
+        <literal>$Rev$</literal> keyword works.  Since the repository
+        has a single, globally increasing revision number, many people
+        assume that it is this number which is reflected by the
+        <literal>$Rev$</literal> keyword's value.  But
+        <literal>$Rev$</literal> expands to show the last revision in
+        which the file <emphasis>changed</emphasis>, not the last
+        revision to which it was updated.  Understanding this clears
+        the confusion, but frustration often remains—without the
+        support of a Subversion keyword to do so, how can you
+        automatically get the global revision number into your
+        files?</para>
+
+      <para>To do this, you need external processing.  Subversion
+        ships with a tool called <command>svnversion</command> which
+        was designed for just this purpose.
+        <command>svnversion</command> crawls your working copy and
+        generates as output the revision(s) it finds.  You can use
+        this program, plus some additionally tooling, to embed that
+        revision information into your files.  For more information on
+        <command>svnversion</command>, see <xref
+        linkend="svn.ref.svnversion"/>.</para>
+
     </sidebar>
 
     <para>Subversion 1.2 introduced a new variant of the keyword




More information about the svnbook-dev mailing list