<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Keyword Substitution</title><link rel="stylesheet" href="styles.css" type="text/css" /><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><link rel="start" href="index.html" title="Version Control with Subversion" /><link rel="up" href="svn.advanced.html" title="Chapter 3. Advanced Topics" /><link rel="prev" href="svn.advanced.props.special.ignore.html" title="Ignoring Unversioned Items" /><link rel="next" href="svn.advanced.sparsedirs.html" title="Sparse Directories" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Keyword Substitution</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="svn.advanced.props.special.ignore.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="svn.advanced.sparsedirs.html">Next</a></td></tr></table><hr /></div><div class="sect1" lang="en" xml:lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a id="svn.advanced.props.special.keywords"></a>Keyword Substitution</h2></div></div></div><p>Subversion has the ability to substitute
<em class="firstterm">keywords</em>—pieces of useful,
dynamic information about a versioned file—into the
contents of the file itself. Keywords generally provide
information about the last modification made to the file.
Because this information changes each time the
file changes, and more importantly, just
<span class="emphasis"><em>after</em></span> the file changes, it is a hassle
for any process except the version control system to keep
the data completely up-to-date. Left to human authors, the
information would inevitably grow stale.</p><p>For example, say you have a document in which you would
like to display the last date on which it was modified. You
could burden every author of that document to, just before
committing their changes, also tweak the part of the
document that describes when it was last changed. But
sooner or later, someone would forget to do that. Instead,
simply ask Subversion to perform keyword substitution on the
<code class="literal">LastChangedDate</code> keyword. You control
where the keyword is inserted into your document by placing
a <em class="firstterm">keyword anchor</em> at the desired
location in the file. This anchor is just a string of text
formatted as
<code class="literal">$</code><em class="replaceable"><code>KeywordName</code></em><code class="literal">$</code>.</p><p>All keywords are case-sensitive where they appear as
anchors in files: you must use the correct capitalization in
order for the keyword to be expanded. You should consider the
value of the <code class="literal">svn:keywords</code> property to be
case-sensitive too—certain keyword names will be recognized
regardless of case, but this behavior is deprecated.</p><p>Subversion defines the list of keywords available for
substitution. That list contains the following five keywords,
some of which have aliases that you can also use:</p><div class="variablelist"><dl><dt><span class="term"><code class="literal">Date</code></span></dt><dd><p>This keyword describes the last time the file was
known to have been changed in the repository, and
is of the form <code class="literal">$Date:
2006-07-22 21:42:37 -0700 (Sat, 22 Jul 2006)
$</code>. It may also be specified as
<code class="literal">LastChangedDate</code>.</p></dd><dt><span class="term"><code class="literal">Revision</code></span></dt><dd><p>This keyword describes the last known revision in
which this file changed in the repository, and looks
something like <code class="literal">$Revision: 144 $</code>.
It may also be specified as
<code class="literal">LastChangedRevision</code> or
<code class="literal">Rev</code>.</p></dd><dt><span class="term"><code class="literal">Author</code></span></dt><dd><p>This keyword describes the last known user to
change this file in the repository, and looks
something like <code class="literal">$Author: harry $</code>.
It may also be specified as
<code class="literal">LastChangedBy</code>.</p></dd><dt><span class="term"><code class="literal">HeadURL</code></span></dt><dd><p>This keyword describes the full URL to the latest
version of the file in the repository, and looks
something like <code class="literal">$HeadURL:
http://svn.collab.net/repos/trunk/README $</code>.
It may be abbreviated as
<code class="literal">URL</code>.</p></dd><dt><span class="term"><code class="literal">Id</code></span></dt><dd><p>This keyword is a compressed combination of the
other keywords. Its substitution looks something like
<code class="literal">$Id: calc.c 148 2006-07-28 21:30:43Z sally
$</code>, and is interpreted to mean that the file
<code class="filename">calc.c</code> was last changed in revision
148 on the evening of July 28, 2006 by the user
<code class="literal">sally</code>.</p></dd></dl></div><p>Several of the previous descriptions use the phrase
“<span class="quote">last known</span>” or similar wording. Keep in mind that
keyword expansion is a client-side operation, and your client
only “<span class="quote">knows</span>” about changes which have occurred in
the repository when you update your working copy to include
those changes. If you never update your working copy, your
keywords will never expand to different values even if those
versioned files are being changed regularly in the
repository.</p><p>Simply adding keyword anchor text to your file does
nothing special. Subversion will never attempt to perform
textual substitutions on your file contents unless
explicitly asked to do so. After all, you might be writing
a document
<sup>[<a id="id360447" href="#ftn.id360447" class="footnote">15</a>]</sup>
about how to use keywords, and you don't want Subversion to
substitute your beautiful examples of un-substituted keyword
anchors!</p><p>To tell Subversion whether or not to substitute keywords
on a particular file, we again turn to the property-related
subcommands. The <code class="literal">svn:keywords</code> property,
when set on a versioned file, controls which keywords will
be substituted on that file. The value is a space-delimited
list of the keyword names or aliases found in the previous
table.</p><p>For example, say you have a versioned file named
<code class="filename">weather.txt</code> that looks like
this:</p><pre class="programlisting">
Here is the latest report from the front lines.
$LastChangedDate$
$Rev$
Cumulus clouds are appearing more frequently as summer approaches.
</pre><p>With no <code class="literal">svn:keywords</code> property set on
that file, Subversion will do nothing special. Now, let's
enable substitution of the
<code class="literal">LastChangedDate</code> keyword.</p><pre class="screen">
$ svn propset svn:keywords "Date Author" weather.txt
property 'svn:keywords' set on 'weather.txt'
$
</pre><p>Now you have made a local property modification on the
<code class="filename">weather.txt</code> file. You will see no
changes to the file's contents (unless you made some of your
own prior to setting the property). Notice that the file
contained a keyword anchor for the <code class="literal">Rev</code>
keyword, yet we did not include that keyword in the property
value we set. Subversion will happily ignore requests to
substitute keywords that are not present in the file, and
will not substitute keywords that are not present in the
<code class="literal">svn:keywords</code> property value.</p><p>Immediately after you commit this property change,
Subversion will update your working file with the new
substitute text. Instead of seeing your keyword anchor
<code class="literal">$LastChangedDate$</code>, you'll see its
substituted result. That result also contains the name of
the keyword, and continues to be bounded by the dollar sign
(<code class="literal">$</code>) characters. And as we predicted, the
<code class="literal">Rev</code> keyword was not substituted because
we didn't ask for it to be.</p><p>Note also that we set the <code class="literal">svn:keywords</code>
property to “<span class="quote">Date Author</span>” yet the keyword
anchor used the alias <code class="literal">$LastChangedDate$</code>
and still expanded correctly.</p><pre class="screen">
Here is the latest report from the front lines.
$LastChangedDate: 2006-07-22 21:42:37 -0700 (Sat, 22 Jul 2006) $
$Rev$
Cumulus clouds are appearing more frequently as summer approaches.
</pre><p>If someone else now commits a change to
<code class="filename">weather.txt</code>, your copy of that file
will continue to display the same substituted keyword value
as before—until you update your working copy. At that
time the keywords in your <code class="filename">weather.txt</code>
file will be re-substituted with information that
reflects the most recent known commit to that file.</p><div class="sidebar"><p class="title"><b>Where's $GlobalRev$?</b></p><p>New users are often confused by how the
<code class="literal">$Rev$</code> 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
<code class="literal">$Rev$</code> keyword's value. But
<code class="literal">$Rev$</code> expands to show the last revision in
which the file <span class="emphasis"><em>changed</em></span>, 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?</p><p>To do this, you need external processing. Subversion
ships with a tool called <span class="command"><strong>svnversion</strong></span> which
was designed for just this purpose.
<span class="command"><strong>svnversion</strong></span> crawls your working copy and
generates as output the revision(s) it finds. You can use
this program, plus some additional tooling, to embed that
revision information into your files. For more information on
<span class="command"><strong>svnversion</strong></span>, see <a class="xref" href="svn.ref.svnversion.html" title="svnversion">the section called “<span class="command"><strong>svnversion</strong></span>”</a>.</p></div><p>Subversion 1.2 introduced a new variant of the keyword
syntax which brought additional, useful—though perhaps
atypical—functionality. You can now tell Subversion
to maintain a fixed length (in terms of the number of bytes
consumed) for the substituted keyword. By using a
double-colon (<code class="literal">::</code>) after the keyword name,
followed by a number of space characters, you define that
fixed width. When Subversion goes to substitute your
keyword for the keyword and its value, it will essentially
replace only those space characters, leaving the overall
width of the keyword field unchanged. If the substituted
value is shorter than the defined field width, there will be
extra padding characters (spaces) at the end of the
substituted field; if it is too long, it is truncated with a
special hash (<code class="literal">#</code>) character just before
the final dollar sign terminator.</p><p>For example, say you have a document in which you have
some section of tabular data reflecting the document's
Subversion keywords. Using the original Subversion keyword
substitution syntax, your file might look something
like:</p><pre class="screen">
$Rev$: Revision of last commit
$Author$: Author of last commit
$Date$: Date of last commit
</pre><p>Now, that looks nice and tabular at the start of things.
But when you then commit that file (with keyword substitution
enabled, of course), you see:</p><pre class="screen">
$Rev: 12 $: Revision of last commit
$Author: harry $: Author of last commit
$Date: 2006-03-15 02:33:03 -0500 (Wed, 15 Mar 2006) $: Date of last commit
</pre><p>The result is not so beautiful. And you might be
tempted to then adjust the file after the substitution so
that it again looks tabular. But that only holds as long as
the keyword values are the same width. If the last
committed revision rolls into a new place value (say, from
99 to 100), or if another person with a longer username
commits the file, stuff gets all crooked again. However, if
you are using Subversion 1.2 or better, you can use the new
fixed-length keyword syntax, define some field widths that
seem sane, and now your file might look like this:</p><pre class="screen">
$Rev:: $: Revision of last commit
$Author:: $: Author of last commit
$Date:: $: Date of last commit
</pre><p>You commit this change to your file. This time,
Subversion notices the new fixed-length keyword syntax, and
maintains the width of the fields as defined by the padding
you placed between the double-colon and the trailing dollar
sign. After substitution, the width of the fields is
completely unchanged—the short values for
<code class="literal">Rev</code> and <code class="literal">Author</code> are
padded with spaces, and the long <code class="literal">Date</code>
field is truncated by a hash character:</p><pre class="screen">
$Rev:: 13 $: Revision of last commit
$Author:: harry $: Author of last commit
$Date:: 2006-03-15 0#$: Date of last commit
</pre><p>The use of fixed-length keywords is especially handy
when performing substitutions into complex file formats that
themselves use fixed-length fields for data, or for which
the stored size of a given data field is overbearingly
difficult to modify from outside the format's native
application (such as for Microsoft Office documents).</p><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>Be aware that because the width of a keyword field is
measured in bytes, the potential for corruption of
multi-byte values exists. For example, a username which
contains some multi-byte UTF-8 characters might suffer
truncation in the middle of the string of bytes which make
up one of those characters. The result will be a mere
truncation when viewed at the byte level, but will likely
appear as a string with an incorrect or garbled final
character when viewed as UTF-8 text. It is conceivable
that certain applications, when asked to load the file,
would notice the broken UTF-8 text and deem the entire
file corrupt, refusing to operate on the file
altogether. So, when limiting keywords to a fixed size,
choose a size that allows for this type of byte-wise
expansion.</p></div><div class="footnotes"><br /><hr width="100" align="left" /><div class="footnote"><p><sup>[<a id="ftn.id360447" href="#id360447" class="para">15</a>] </sup>… or maybe even a section of a book …</p></div></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="svn.advanced.props.special.ignore.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="svn.advanced.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="svn.advanced.sparsedirs.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Ignoring Unversioned Items </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Sparse Directories</td></tr></table></div></body></html>
