ch03-advanced-topics.xml - svnbook - Project Hosting on Google Code

‹r3563

r3710

Source path: svn/ trunk/ src/ en/ book/ ch03-advanced-topics.xml

<chapter id="svn.advanced">
  <title>Advanced Topics</title>

  <para>If you've been reading this book chapter by chapter, from
    start to finish, you should by now have acquired enough
    knowledge to use the Subversion client to perform the most
    common version control operations.  You understand how to
    check out a working copy from a Subversion repository.  You are
    comfortable with submitting and receiving changes using the
    <command>svn commit</command> and <command>svn update</command>
    operations.  You've probably even developed a reflex that causes
    you to run the <command>svn status</command> command almost
    unconsciously.  For all intents and purposes, you are ready to
    use Subversion in a typical environment.</para>

  <para>But the Subversion feature set doesn't stop at <quote>common
    version control operations.</quote>  It has other bits of
    functionality besides just communicating file and
    directory changes to and from a central repository.</para>

  <para>This chapter highlights some of Subversion's features that,
    while important, aren't part of the typical user's daily routine.
    It assumes that you are familiar with Subversion's basic file and
    directory versioning capabilities.  If you aren't, you'll want to
    first read <xref linkend="svn.basic" /> and <xref
    linkend="svn.tour" />.  Once you've mastered those basics and
    consumed this chapter, you'll be a Subversion power user!</para>


  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.tour.revs.specifiers">
    <title>Revision Specifiers</title>

    <para>As we described in <xref linkend="svn.basic.in-action.revs"
      />, revision numbers in Subversion are pretty
      straightforward&mdash;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 give 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: <firstterm>revision keywords</firstterm>
      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>
      
      <indexterm>
        <primary>revisions</primary>
        <secondary>revision keywords</secondary>
      </indexterm>
      <indexterm>
        <primary>HEAD</primary>
      </indexterm>
      <indexterm>
        <primary>BASE</primary>
      </indexterm>
      <indexterm>
        <primary>COMMITTED</primary>
      </indexterm>
      <indexterm>
        <primary>PREV</primary>
      </indexterm>

      <para>The Subversion client understands a number of revision
        keywords.  These keywords can be used instead of integer
        arguments to the <option>--revision</option>
        (<option>-r</option>) option, and are resolved into specific
        revision numbers by Subversion:</para>

      <variablelist>
        
        <varlistentry>
          <term><literal>HEAD</literal></term>
          <listitem>
            <para>The latest (or <quote>youngest</quote>) revision in
              the repository.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><literal>BASE</literal></term>
          <listitem>
            <para>The revision number of an item in a working copy.
              If the item has been locally modified, this refers to
              the way the item appears without those local
              modifications.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><literal>COMMITTED</literal></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><literal>PREV</literal></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>&minus;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&mdash;they don't apply
        to repository URLs.  <literal>HEAD</literal>, on the other
        hand, can be used in conjunction with both of these path
        types.</para>
      
      <para>Here are some examples of revision keywords in
        action:</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>
      
      <indexterm>
        <primary>revisions</primary>
        <secondary>specified as dates</secondary>
      </indexterm>

      <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>-r</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 {2006-02-17}
$ svn checkout -r {15:30}
$ svn checkout -r {15:30:00.200000}
$ svn checkout -r {"2006-02-17 15:30"}
$ svn checkout -r {"2006-02-17 15:30 +0230"}
$ svn checkout -r {2006-02-17T15:30}
$ svn checkout -r {2006-02-17T15:30Z}
$ svn checkout -r {2006-02-17T15:30-04:00}
$ svn checkout -r {20060217T1530}
$ svn checkout -r {20060217T1530Z}
$ svn checkout -r {20060217T1530-0500}
&hellip;
</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 {2006-11-28}
------------------------------------------------------------------------
r12 | ira | 2006-11-27 12:31:51 -0600 (Mon, 27 Nov 2006) | 6 lines
&hellip;
</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>2006-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, such as
          <literal>2006-11-27</literal>, Subversion assumes a time of
          00:00:00, so looking for the most recent revision won't
          return anything on the 27th.</para>


        <para>If you want to include the 27th in your search, you can
          either specify the 27th with the time (<literal>{"2006-11-27
          23:59"}</literal>), or just specify the next day
          (<literal>{2006-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 {2006-11-20}:{2006-11-29}
&hellip;
</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.  Subversion's
          ability to correctly convert revision dates into real
          revision numbers depends on revision datestamps maintaining
          a sequential ordering&mdash;the younger the revision, the
          younger its timestamp.  If this ordering isn't maintained,
          you will likely find that trying to use dates to specify
          revision ranges in your repository doesn't always return the
          data you might have expected.</para>
      </warning>
        
    </sect2>
      
  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.advanced.props">
    <title>Properties</title>
    <indexterm>
      <primary>properties</primary>
    </indexterm>

    <para>We've already covered in detail how Subversion stores and
      retrieves various versions of files and directories in its
      repository.  Whole chapters have been devoted to this most
      fundamental piece of functionality provided by the tool.  And
      if the versioning support stopped there, Subversion would still
      be complete from a version control perspective.</para>

    <para>But it doesn't stop there.</para>

    <para>In addition to versioning your directories and files,
      Subversion provides interfaces for adding, modifying, and
      removing versioned metadata on each of your versioned
      directories and files.  We refer to this metadata as
      <firstterm>properties</firstterm>, and they can be thought of as
      two-column tables that map property names to arbitrary values
      attached to each item in your working copy.  Generally speaking,
      the names and values of the properties can be whatever you want
      them to be, with the constraint that the names must contain only
      ASCII characters.  And the best part about these properties is
      that they, too, are versioned, just like the textual contents of
      your files.  You can modify, commit, and revert property changes
      as easily as you can file content changes.  And the sending and
      receiving of property changes occurs as part of your typical
      commit and update operations&mdash;you don't have to change your
      basic processes to accommodate them.</para>

    <note>
      <para>Subversion has reserved the set of properties whose names
        begin with <literal>svn:</literal> as its own.  While there
        are only a handful of such properties in use today, you should
        avoid creating custom properties for your own needs whose names
        begin with this prefix.  Otherwise, you run the risk that a
        future release of Subversion will grow support for a feature
        or behavior driven by a property of the same name but with
        perhaps an entirely different interpretation.</para>
    </note>

    <para>Properties show up elsewhere in Subversion, too.  Just as
      files and directories may have arbitrary property names and
      values attached to them, each revision as a whole may have
      arbitrary properties attached to it.  The same constraints
      apply&mdash;human-readable names and anything-you-want binary
      values.  The main difference is that revision properties are not
      versioned.  In other words, if you change the value of, or
      delete, a revision property, there's no way, within the scope of
      Subversion's functionality, to recover the previous value.</para>

    <para>Subversion has no particular policy regarding the use of
      properties.  It asks only that you not use property names that
      begin with the prefix <literal>svn:</literal>.  That's the
      namespace that it sets aside for its own use.  And Subversion
      does, in fact, use properties&mdash;both the versioned and
      unversioned variety.  Certain versioned properties have special
      meaning or effects when found on files and directories, or they
      house a particular bit of information about the revisions on
      which they are found.  Certain revision properties are
      automatically attached to revisions by Subversion's commit
      process, and they carry information about the revision.  Most of
      these properties are mentioned elsewhere in this or other
      chapters as part of the more general topics to which they are
      related.  For an exhaustive list of Subversion's predefined
      properties, see <xref linkend="svn.ref.properties" />.</para>

    <note>
      <para>While Subversion automatically attaches properties
        (<literal>svn:date</literal>, <literal>svn:author</literal>,
        <literal>svn:log</literal>, and so on) to revisions, it does
        <emphasis>not</emphasis> presume thereafter the existence of
        those properties, and neither should you or the tools you use to
        interact with your repository.  Revision properties can be
        deleted programmatically or via the client (if allowed by the
        repository hooks) without damaging Subversion's ability to
        function.  So, when writing scripts which operate on your
        Subversion repository data, do not make the mistake of
        assuming that any particular revision property exists on a
        revision.</para>
    </note>

    <para>In this section, we will examine the utility&mdash;both to
      users of Subversion and to Subversion itself&mdash;of property
      support.  You'll learn about the property-related
      <command>svn</command> subcommands and how property
      modifications affect your normal Subversion workflow.</para>

    <!-- =============================================================== -->
    <sect2 id="svn.advanced.props.why">
      <title>Why Properties?</title>

      <para>Just as Subversion uses properties to store extra
        information about the files, directories, and revisions that
        it contains, you might also find properties to be of similar
        use.  You might find it useful to have a place
        close to your versioned data to hang custom metadata about
        that data.</para>

      <para>Say you wish to design a web site that houses many digital
        photos and displays them with captions and a datestamp.  Now,
        your set of photos is constantly changing, so you'd like to
        have as much of this site automated as possible.  These photos
        can be quite large, so as is common with sites of this nature,
        you want to provide smaller thumbnail images to your site
        visitors.</para>

      <para>Now, you can get this functionality using traditional
        files.  That is, you can have your
        <filename>image123.jpg</filename> and an
        <filename>image123-thumbnail.jpg</filename> side by side in a
        directory.  Or if you want to keep the filenames the same, you
        might have your thumbnails in a different directory, such as
        <filename>thumbnails/image123.jpg</filename>.  You can also
        store your captions and datestamps in a similar fashion, again
        separated from the original image file.  But the problem here
        is that your collection of files multiplies with each new
        photo added to the site.</para>

      <para>Now consider the same web site deployed in a way that
        makes use of Subversion's file properties.  Imagine having a
        single image file, <filename>image123.jpg</filename>, with
        properties set on that file that are named
        <literal>caption</literal>, <literal>datestamp</literal>, and
        even <literal>thumbnail</literal>.  Now your working copy
        directory looks much more manageable&mdash;in fact, it looks
        to the casual browser like there are nothing but image files
        in it.  But your automation scripts know better.  They know
        that they can use <command>svn</command> (or better yet, they
        can use the Subversion language bindings&mdash;see <xref
        linkend="svn.developer.usingapi" />) to dig out the extra
        information that your site needs to display without having to
        read an index file or play path manipulation games.</para>

      <note>
        <para>While Subversion places few restrictions on the names
          and values you use for properties, it has not been designed
          to optimally carry large property values or large sets of
          properties on a given file or directory.  Subversion
          commonly holds all the property names and values associated
          with a single item in memory at the same time, which can
          cause detrimental performance or failed operations when
          extremely large property sets are used.</para>
      </note>

      <para>Custom revision properties are also frequently used.  One
        common such use is a property whose value contains an issue
        tracker ID with which the revision is associated, perhaps
        because the change made in that revision fixes a bug filed in
        the tracker issue with that ID.  Other uses include hanging
        more friendly names on the revision&mdash;it might be hard to
        remember that revision 1935 was a fully tested revision.  But
        if there's, say, a <literal>test-results</literal> property on
        that revision with the value <literal>all passing</literal>,
        that's meaningful information to have.</para>

      <sidebar>
        <title>Searchability (or, Why <emphasis>Not</emphasis>
          Properties)</title>

        <para>For all their utility, Subversion properties&mdash;or,
          more accurately, the available interfaces to them&mdash;have
          a major shortcoming: while it is a simple matter to
          <emphasis>set</emphasis> a custom property,
          <emphasis>finding</emphasis> that property later is a whole
          different ball of wax.</para>


        <para>Trying to locate a custom revision property generally
          involves performing a linear walk across all the revisions
          of the repository, asking of each revision, <quote>Do you have the
          property I'm looking for?</quote>  Trying to find a custom
          versioned property is painful, too, and often involves a
          recursive <command>svn propget</command> across an entire
          working copy.  In your situation, that might not be as bad
          as a linear walk across all revisions.  But it certainly
          leaves much to be desired in terms of both performance and
          likelihood of success, especially if the scope of your
          search would require a working copy from the root of your
          repository.</para>

        <para>For this reason, you might choose&mdash;especially in
          the revision property use case&mdash;to simply add your
          metadata to the revision's log message using some
          policy-driven (and perhaps programmatically enforced)
          formatting that is designed to be quickly parsed from the
          output of <command>svn log</command>.  It is quite common to
          see the following in Subversion log messages:</para>

        <programlisting>
Issue(s): IZ2376, IZ1919
Reviewed by:  sally

This fixes a nasty segfault in the wort frabbing process
&hellip;
</programlisting>

        <para>But here again lies some misfortune.  Subversion doesn't
          yet provide a log message templating mechanism, which would
          go a long way toward helping users be consistent with the
          formatting of their log-embedded revision metadata.</para>

      </sidebar>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.advanced.props.manip">
      <title>Manipulating Properties</title>

      <para>The <command>svn</command> program affords a few ways to
        add or modify file and directory properties.  For properties
        with short, human-readable values, perhaps the simplest way to
        add a new property is to specify the property name and value
        on the command line of the <command>svn propset</command>
        subcommand:</para>

      <screen>
$ svn propset copyright '(c) 2006 Red-Bean Software' calc/button.c
property 'copyright' set on 'calc/button.c'
$
</screen>
       
      <para>But we've been touting the flexibility that Subversion
        offers for your property values.  And if you are planning to
        have a multiline textual, or even binary, property value, you
        probably do not want to supply that value on the command line.
        So the <command>svn propset</command> subcommand takes a
        <option>--file</option> (<option>-F</option>) option for
        specifying the name of a file that contains the new property
        value.</para>

      <screen>
$ svn propset license -F /path/to/LICENSE calc/button.c
property 'license' set on 'calc/button.c'
$
</screen>

      <para>There are some restrictions on the names you can use for
        properties.  A property name must start with a letter, a colon
        (<literal>:</literal>), or an underscore
        (<literal>_</literal>); after that, you can also use digits,
        hyphens (<literal>-</literal>), and periods
        (<literal>.</literal>).
          <footnote>
            <para>If you're familiar with XML, this is pretty much the
            ASCII subset of the syntax for XML <quote>Name</quote>.</para>
          </footnote>
      </para>

      <para>In addition to the <command>propset</command> command, the
        <command>svn</command> program supplies the
        <command>propedit</command> command.  This command uses the
        configured editor program (see <xref
        linkend="svn.advanced.confarea.opts.config" />) to add or
        modify properties.  When you run the command,
        <command>svn</command> invokes your editor program on a
        temporary file that contains the current value of the property
        (or that is empty, if you are adding a new property).  Then,
        you just modify that value in your editor program until it
        represents the new value you wish to store for the property,
        save the temporary file, and then exit the editor program.  If
        Subversion detects that you've actually changed the existing
        value of the property, it will accept that as the new property
        value.  If you exit your editor without making any changes, no
        property modification will occur:</para>

      <screen>
$ svn propedit copyright calc/button.c  ### exit the editor without changes
No changes to property 'copyright' on 'calc/button.c'
$
</screen>

      <para>We should note that, as with other <command>svn</command>
        subcommands, those related to properties can act on multiple
        paths at once.  This enables you to modify properties on whole
        sets of files with a single command.  For example, we could
        have done the following:</para>

      <screen>
$ svn propset copyright '(c) 2006 Red-Bean Software' calc/*
property 'copyright' set on 'calc/Makefile'
property 'copyright' set on 'calc/button.c'
property 'copyright' set on 'calc/integer.c'
&hellip;
$
</screen>

      <para>All of this property adding and editing isn't really very
        useful if you can't easily get the stored property value.  So
        the <command>svn</command> program supplies two subcommands
        for displaying the names and values of properties stored on
        files and directories.  The <command>svn proplist</command>
        command will list the names of properties that exist on a
        path.  Once you know the names of the properties on the node,
        you can request their values individually using <command>svn
        propget</command>.  This command will, given a property name and a path (or set of
        paths), print the value of the property to
        the standard output stream.</para>

      <screen>
$ svn proplist calc/button.c
Properties on 'calc/button.c':
  copyright
  license
$ svn propget copyright calc/button.c
(c) 2006 Red-Bean Software
</screen>

      <para>There's even a variation of the
        <command>proplist</command> command that will list both the
        name and the value for all of the properties.  Simply supply the
        <option>--verbose</option> (<option>-v</option>) option.</para>

      <screen>
$ svn proplist -v calc/button.c
Properties on 'calc/button.c':
  copyright
    (c) 2006 Red-Bean Software
  license
    ================================================================
    Copyright (c) 2006 Red-Bean Software.  All rights reserved.

    Redistribution and use in source and binary forms, with or without
    modification, are permitted provided that the following conditions 
    are met:

    1. Redistributions of source code must retain the above copyright
    notice, this list of conditions, and the recipe for Fitz's famous
    red-beans-and-rice.
    &hellip;
</screen>

      <para>The last property-related subcommand is
        <command>propdel</command>.  Since Subversion allows you to
        store properties with empty values, you can't remove a
        property altogether using <command>svn propedit</command> or
        <command>svn propset</command>.  For example, this command will
        <emphasis>not</emphasis> yield the desired effect:</para>

      <screen>
$ svn propset license "" calc/button.c
property 'license' set on 'calc/button.c'
$ svn proplist -v calc/button.c
Properties on 'calc/button.c':
  copyright
    (c) 2006 Red-Bean Software
  license
    
$
</screen>

      <para>You need to use the <command>propdel</command> subcommand
        to delete properties altogether.  The syntax is similar to the
        other property commands:</para>

      <screen>
$ svn propdel license calc/button.c
property 'license' deleted from 'calc/button.c'.
$ svn proplist -v calc/button.c
Properties on 'calc/button.c':
  copyright
    (c) 2006 Red-Bean Software
$
</screen>

      <para>Remember those unversioned revision properties?  You can
        modify those, too, using the same <command>svn</command>
        subcommands that we just described.  Simply add the
        <option>--revprop</option> command-line parameter and specify
        the revision whose property you wish to modify.  Since
        revisions are global, you don't need to specify a target path
        to these property-related commands so long as you are
        positioned in a working copy of the repository whose
        revision property you wish to modify.  Otherwise, you can
        simply provide the URL of any path in the repository of
        interest (including the repository's root URL).  For example,
        you might want to replace the commit log message of an
        existing revision.
        <footnote>
          <para>Fixing spelling errors, grammatical gotchas, and
            <quote>just-plain-wrongness</quote> in commit log
            messages is perhaps the most common use case for the
            <option>--revprop</option> option.</para>
        </footnote>
        If your current working directory is part of a working copy of
        your repository, you can simply run the
        <command>svn propset</command> command with no target path:</para>


      <screen>
$ svn propset svn:log "* button.c: Fix a compiler warning." -r11 --revprop
property 'svn:log' set on repository revision '11'
$
</screen>

      <para>But even if you haven't checked out a working copy from
        that repository, you can still effect the property change by
        providing the repository's root URL:</para>

      <screen>
$ svn propset svn:log "* button.c: Fix a compiler warning." -r11 --revprop \
              http://svn.example.com/repos/project
property 'svn:log' set on repository revision '11'
$
</screen>

      <para>Note that the ability to modify these unversioned
        properties must be explicitly added by the repository
        administrator (see <xref linkend="svn.reposadmin.maint.setlog" />).
        That's because the properties aren't versioned, so you run the risk of
        losing information if you aren't careful with your edits.
        The repository administrator can set up methods to protect
        against this loss, and by default, modification of
        unversioned properties is disabled.</para>

      <tip>
        <para>Users should, where possible, use <command>svn
          propedit</command> instead of <command>svn
          propset</command>.  While the end result of the commands is
          identical, the former will allow them to see the current
          value of the property that they are about to change, which helps
          them to verify that they are, in fact, making the change
          they think they are making.  This is especially true when
          modifying unversioned revision properties.  Also, it is
          significantly easier to modify multiline property values in
          a text editor than at the command line.</para>
      </tip>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.advanced.props.workflow">
      <title>Properties and the Subversion Workflow</title>

      <para>Now that you are familiar with all of the
        property-related <command>svn</command> subcommands, let's see
        how property modifications affect the usual Subversion
        workflow.  As we mentioned earlier, file and directory
        properties are versioned, just like your file contents.  As a
        result, Subversion provides the same opportunities for
        merging&mdash;cleanly or with conflicts&mdash;someone
        else's modifications into your own.</para>

      <para>As with file contents, your property changes are local
        modifications, made permanent only when you commit them to the
        repository with <command>svn commit</command>.  Your property
        changes can be easily unmade, too&mdash;the <command>svn
        revert</command> command will restore your files and
        directories to their unedited states&mdash;contents, properties,
        and all.  Also, you can receive interesting information about
        the state of your file and directory properties by using the
        <command>svn status</command> and <command>svn diff</command>
        commands.</para>

      <screen>
$ svn status calc/button.c
 M     calc/button.c
$ svn diff calc/button.c
Property changes on: calc/button.c
___________________________________________________________________
Name: copyright
   + (c) 2006 Red-Bean Software

$
</screen>

      <para>Notice how the <command>status</command> subcommand
        displays <literal>M</literal> in the second column instead of
        the first.  That is because we have modified the properties on
        <filename>calc/button.c</filename>, but not its textual
        contents.  Had we changed both, we would have seen
        <literal>M</literal> in the first column, too.  (We cover
        <command>svn status</command> in <xref
        linkend="svn.tour.cycle.examine.status" />).</para>

      <sidebar>
        <title>Property Conflicts</title>

        <para>As with file contents, local property modifications can
          conflict with changes committed by someone else.  If you
          update your working copy directory and receive property
          changes on a versioned object that clash with your own,
          Subversion will report that the object is in a conflicted
          state.</para>
 
        <screen>
$ svn update calc
M  calc/Makefile.in
Conflict for property 'linecount' discovered on 'calc/button.c'.
Select: (p) postpone, (df) diff-full, (e) edit,
        (s) show all options: p
 C calc/button.c
Updated to revision 143.
$ 
</screen>
         
        <para>Subversion will also create, in the same directory as
          the conflicted object, a file with a
          <filename>.prej</filename> extension that contains the
          details of the conflict.  You should examine the contents of
          this file so you can decide how to resolve the conflict.
          Until the conflict is resolved, you will see a
          <literal>C</literal> in the second column of <command>svn
          status</command> output for that object, and attempts to
          commit your local modifications will fail.</para>

        <screen>
$ svn status calc
 C     calc/button.c
?      calc/button.c.prej
$ cat calc/button.c.prej 
Trying to change property 'linecount' from '1267' to '1301',
but property has been locally changed from '1267' to '1256'.
$
</screen>
 
        <para>To resolve property conflicts, simply ensure that the
          conflicting properties contain the values that they should,
          and then use the <command>svn resolved</command> command to
          alert Subversion that you have manually resolved the
          problem.</para>

      </sidebar>

      <para>You might also have noticed the nonstandard way that
        Subversion currently displays property differences.  You can
        still use <command>svn diff</command> and redirect its output
        to create a usable patch file.  The <command>patch</command>
        program will ignore property patches&mdash;as a rule, it
        ignores any noise it can't understand.  This does,
        unfortunately, mean that to fully apply a patch generated by
        <command>svn diff</command>, any property modifications will
        need to be applied by hand.</para>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.advanced.props.auto">
      <title>Automatic Property Setting</title>

      <para>Properties are a powerful feature of Subversion, acting as
        key components of many Subversion features discussed elsewhere
        in this and other chapters&mdash;textual diff and merge
        support, keyword substitution, newline translation, and so on.  But
        to get the full benefit of properties, they must be set on the
        right files and directories.  Unfortunately, that
        step can be easily forgotten in the routine of things, especially
        since failing to set a property doesn't usually result in an
        obvious error (at least compared to, say, failing to
        add a file to version control).  To help your properties get
        applied to the places that need them, Subversion provides a
        couple of simple but useful features.</para>

      <para>Whenever you introduce a file to version control using the
        <command>svn add</command> or <command>svn import</command>
        commands, Subversion tries to assist by setting some common
        file properties automatically.  First, on operating systems
        whose filesystems support an execute permission bit,
        Subversion will automatically set the
        <literal>svn:executable</literal> property on newly added or
        imported files whose execute bit is enabled.  (See <xref
        linkend="svn.advanced.props.special.executable" /> later in
        this chapter for more about this property.)</para>

      <para>Second, Subversion tries to determine the file's MIME
        type.  If you've configured a
        <literal>mime-types-files</literal> runtime configuration
        parameter, Subversion will try to find a MIME type mapping in
        that file for your file's extension.  If it finds such a
        mapping, it will set your file's
        <literal>svn:mime-type</literal> property to the MIME type it
        found.  If no mapping file is configured, or no mapping for
        your file's extension could be found, Subversion runs a very
        basic heuristic to determine whether the file contains nontextual
        content.  If so, it automatically sets the
        <literal>svn:mime-type</literal> property on that file to
        <literal>application/octet-stream</literal> (the generic
        <quote>this is a collection of bytes</quote> MIME type).  Of
        course, if Subversion guesses incorrectly, or if you wish to
        set the <literal>svn:mime-type</literal> property to something
        more precise&mdash;perhaps <literal>image/png</literal> or
        <literal>application/x-shockwave-flash</literal>&mdash;you can
        always remove or edit that property.  (For more on
        Subversion's use of MIME types, see <xref
        linkend="svn.advanced.props.special.mime-type" /> later in
        this chapter.)</para>

      <para>Subversion also provides, via its runtime configuration
        system (see <xref linkend="svn.advanced.confarea" />), a more
        flexible automatic property setting feature that allows you
        to create mappings of filename patterns to property names and
        values.  Once again, these mappings affect adds and imports,
        and can not only override the default MIME type decision made
        by Subversion during those operations, but can also set
        additional Subversion or custom properties, too.  For example,
        you might create a mapping that says that anytime you add
        JPEG files&mdash;ones whose names match the pattern
        <literal>*.jpg</literal>&mdash;Subversion should automatically
        set the <literal>svn:mime-type</literal> property on those
        files to <literal>image/jpeg</literal>.  Or perhaps any files
        that match <literal>*.cpp</literal> should have
        <literal>svn:eol-style</literal> set to
        <literal>native</literal>, and <literal>svn:keywords</literal>
        set to <literal>Id</literal>.  Automatic property support is
        perhaps the handiest property-related tool in the Subversion
        toolbox.  See <xref
        linkend="svn.advanced.confarea.opts.config"/> for more about
        configuring that support.</para>


    </sect2>     
  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.advanced.props.file-portability">
    <title>File Portability</title>

    <para>Fortunately for Subversion users who routinely find
      themselves on different computers with different operating
      systems, Subversion's command-line program behaves almost
      identically on all those systems.  If you know how to wield
      <command>svn</command> on one platform, you know how to wield it
      everywhere.</para>

    <para>However, the same is not always true of other general classes
      of software or of the actual files you keep in Subversion.  For
      example, on a Windows machine, the definition of a <quote>text
      file</quote> would be similar to that used on a Linux box, but
      with a key difference&mdash;the character sequences used to mark
      the ends of the lines of those files.  There are other
      differences, too.  Unix platforms have (and Subversion supports)
      symbolic links; Windows does not.  Unix platforms use filesystem
      permission to determine executability; Windows uses filename
      extensions.</para>

    <para>Because Subversion is in no position to unite the whole
      world in common definitions and implementations of all of these
      things, the best it can do is to try to help make your life
      simpler when you need to work with your versioned files and
      directories on multiple computers and operating systems.  This
      section describes some of the ways Subversion does this.</para>

    <!-- =============================================================== -->
    <sect2 id="svn.advanced.props.special.mime-type">
      <title>File Content Type</title>
      
      <para>Subversion joins the ranks of the many applications that
        recognize and make use of Multipurpose Internet Mail
        Extensions (MIME) content types.  Besides being a
        general-purpose storage location for a file's content type,
        the value of the <literal>svn:mime-type</literal> file
        property determines some behavioral characteristics of
        Subversion itself.</para>

      <sidebar>
        <title>Identifying File Types</title>
    
        <para>Various programs on most modern operating systems make
          assumptions about the type and format of the contents of a
          file by the file's name, specifically its file extension.
          For example, files whose names end in
          <filename>.txt</filename> are generally assumed to be
          human-readable; that is, able to be understood by simple perusal
          rather than requiring complex processing to decipher.  Files
          whose names end in <filename>.png</filename>, on the other
          hand, are assumed to be of the Portable Network Graphics
          type&mdash;not human-readable at all, and sensible only when
          interpreted by software that understands the PNG format and
          can render the information in that format as a raster
          image.</para>

        <para>Unfortunately, some of those extensions have changed
          their meanings over time.  When personal computers first appeared,
          a file named <filename>README.DOC</filename> would have
          almost certainly been a plain-text file, just like today's
          <filename>.txt</filename> files.  But by the mid-1990s, you
          could almost bet that a file of that name would not be a
          plain-text file at all, but instead a Microsoft Word document
          in a proprietary, non-human-readable format.  But this
          change didn't occur overnight&mdash;there was certainly a
          period of confusion for computer users over what exactly
          they had in hand when they saw a <filename>.DOC</filename>
          file.
          <footnote>
            <para>You think that was rough?  During that same era,
              WordPerfect also used <filename>.DOC</filename> for their
              proprietary file format's preferred extension!</para>
          </footnote>
        </para>

        <para>The popularity of computer networking cast still more
          doubt on the mapping between a file's name and its content.
          With information being served across networks and generated
          dynamically by server-side scripts, there was often no real
          file per se, and therefore no filename.  Web
          servers, for example, needed some other way to tell browsers
          what they were downloading so that the browser could do something
          intelligent with that information, whether that was to
          display the data using a program registered to handle that
          datatype or to prompt the user for where on the client
          machine to store the downloaded data.</para>

        <para>Eventually, a standard emerged for, among other things,
          describing the contents of a data stream.  In 1996, RFC 2045
          was published.  It was the first of five RFCs describing
          MIME.  It describes the concept of media types and subtypes
          and recommends a syntax for the representation of those
          types.  Today, MIME media types&mdash;or <quote>MIME
          types</quote>&mdash;are used almost universally across
          email applications, web servers, and other software as the
          de facto mechanism for clearing up the file content
          confusion.</para>

      </sidebar>
    
      <para>For example, one of the benefits that Subversion typically
        provides is contextual, line-based merging of changes received
        from the server during an update into your working file.  But
        for files containing nontextual data, there is often no
        concept of a <quote>line.</quote>  So, for versioned files
        whose <literal>svn:mime-type</literal> property is set to a
        nontextual MIME type (generally, something that doesn't begin
        with <literal>text/</literal>, though there are exceptions),
        Subversion does not attempt to perform contextual merges
        during updates.  Instead, any time you have locally modified a
        binary working copy file that is also being updated, your file
        is left untouched and Subversion creates two new files.  One
        file has a <filename>.oldrev</filename> extension and contains
        the BASE revision of the file.  The other file has a
        <filename>.newrev</filename> extension and contains the
        contents of the updated revision of the file.  This behavior
        is really for the protection of the user against failed
        attempts at performing contextual merges on files that simply
        cannot be contextually merged.</para>

      <warning>
        <para>The <literal>svn:mime-type</literal> property, when set
          to a value that does not indicate textual file contents, can
          cause some unexpected behaviors with respect to other
          properties.  For example, since the idea of line endings
          (and therefore, line-ending conversion) makes no sense when
          applied to nontextual files, Subversion will prevent you
          from setting the <literal>svn:eol-style</literal> property
          on such files.  This is obvious when attempted on a single
          file target&mdash;<command>svn propset</command> will error
          out.  But it might not be as clear if you perform a
          recursive property set, where Subversion will silently skip
          over files that it deems unsuitable for a given
          property.</para>
      </warning>

      <para>Beginning in Subversion 1.5, users can configure a new
        <literal>mime-types-file</literal> runtime configuration
        parameter, which identifies the location of a MIME types
        mapping file.  Subversion will consult this mapping file to
        determine the MIME type of newly added and imported
        files.</para>

      <para>Also, if the <literal>svn:mime-type</literal> property is
        set, then the Subversion Apache module will use its value to
        populate the <literal>Content-type:</literal> HTTP header when
        responding to GET requests.  This gives your web browser a
        crucial clue about how to display a file when you use it to
        peruse your Subversion repository's contents.</para>

    </sect2>
  
    <!-- =============================================================== -->
    <sect2 id="svn.advanced.props.special.executable">
      <title>File Executability</title>
 
      <para>On many operating systems, the ability to execute a file
        as a command is governed by the presence of an execute
        permission bit.  This bit usually defaults to being disabled,
        and must be explicitly enabled by the user for each file that
        needs it.  But it would be a monumental hassle to have to
        remember exactly which files in a freshly checked-out working
        copy were supposed to have their executable bits toggled on,
        and then to have to do that toggling.  So, Subversion provides
        the <literal>svn:executable</literal> property as a way to
        specify that the executable bit for the file on which that
        property is set should be enabled, and Subversion honors that
        request when populating working copies with such files.</para>

      <para>This property has no effect on filesystems that have no
        concept of an executable permission bit, such as FAT32 and
        NTFS.
        <footnote>
          <para>The Windows filesystems use file extensions (such as
            <filename>.EXE</filename>, <filename>.BAT</filename>, and
            <filename>.COM</filename>) to denote executable
            files.</para>
        </footnote>
        Also, although it has no defined values, Subversion will force
        its value to <literal>*</literal> when setting this property.
        Finally, this property is valid only on files, not on
        directories.</para>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.advanced.props.special.eol-style">
      <title>End-of-Line Character Sequences</title>

      <para>Unless otherwise noted using a versioned file's
        <literal>svn:mime-type</literal> property, Subversion
        assumes the file contains human-readable data.  Generally
        speaking, Subversion uses this knowledge only to determine
        whether contextual difference reports for that file are
        possible.  Otherwise, to Subversion, bytes are bytes.</para>
      
      <para>This means that by default, Subversion doesn't pay any
        attention to the type of <firstterm>end-of-line (EOL)
        markers</firstterm> used in your files.  Unfortunately,
        different operating systems have different conventions about
        which character sequences represent the end of a line of text
        in a file.  For example, the usual line-ending token used by
        software on the Windows platform is a pair of ASCII control
        characters&mdash;a carriage return (<literal>CR</literal>)
        followed by a line feed (<literal>LF</literal>).  Unix
        software, however, just uses the <literal>LF</literal>
        character to denote the end of a line.</para>


      <para>Not all of the various tools on these operating systems
        understand files that contain line endings in a format that
        differs from the <firstterm>native line-ending
        style</firstterm> of the operating system on which they are
        running.  So, typically, Unix programs treat the
        <literal>CR</literal> character present in Windows files as a
        regular character (usually rendered as <literal>^M</literal>),
        and Windows programs combine all of the lines of a Unix file
        into one giant line because no carriage return-linefeed (or
        <literal>CRLF</literal>) character combination was found to
        denote the ends of the lines.</para>

      <para>This sensitivity to foreign EOL markers can be
        frustrating for folks who share a file across different
        operating systems.  For example, consider a source code
        file, and developers that edit this file on both Windows and
        Unix systems.  If all the developers always use tools that
        preserve the line-ending style of the file, no problems
        occur.</para>

      <para>But in practice, many common tools either fail to
        properly read a file with foreign EOL markers, or
        convert the file's line endings to the native style when the
        file is saved.  If the former is true for a developer, he
        has to use an external conversion utility (such as
        <command>dos2unix</command> or its companion,
        <command>unix2dos</command>) to prepare the file for
        editing.  The latter case requires no extra preparation.
        But both cases result in a file that differs from the
        original quite literally on every line!  Prior to committing
        his changes, the user has two choices.  Either he can use a
        conversion utility to restore the modified file to the same
        line-ending style that it was in before his edits were made,
        or he can simply commit the file&mdash;new EOL markers and
        all.</para>

      <para>The result of scenarios like these include wasted time
        and unnecessary modifications to committed files.  Wasted
        time is painful enough.  But when commits change every line
        in a file, this complicates the job of determining which of
        those lines were changed in a nontrivial way.  Where was
        that bug really fixed?  On what line was a syntax error
        introduced?</para>

      <para>The solution to this problem is the
        <literal>svn:eol-style</literal> property.  When this
        property is set to a valid value, Subversion uses it to
        determine what special processing to perform on the file so
        that the file's line-ending style isn't flip-flopping with
        every commit that comes from a different operating
        system.  The valid values are:</para>

      <variablelist>
        <varlistentry>
          <term><literal>native</literal></term>
          <listitem>
            <para>This causes the file to contain the EOL markers
              that are native to the operating system on which
              Subversion was run.  In other words, if a user on a
              Windows machine checks out a working copy that
              contains a file with an
              <literal>svn:eol-style</literal> property set to
              <literal>native</literal>, that file will contain
              <literal>CRLF</literal> EOL markers.  A Unix user
              checking out a working copy that contains the same
              file will see <literal>LF</literal> EOL markers in his
              copy of the file.</para>

            <para>Note that Subversion will actually store the file
              in the repository using normalized
              <literal>LF</literal> EOL markers regardless of the
              operating system.  This is basically transparent to
              the user, though.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>CRLF</literal></term>
          <listitem>
            <para>This causes the file to contain
              <literal>CRLF</literal> sequences for EOL markers,
              regardless of the operating system in use.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>LF</literal></term>
          <listitem>
            <para>This causes the file to contain
              <literal>LF</literal> characters for EOL markers,
              regardless of the operating system in use.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>CR</literal></term>
          <listitem>
            <para>This causes the file to contain
              <literal>CR</literal> characters for EOL markers,
              regardless of the operating system in use.  This
              line-ending style is not very common.</para>
          </listitem>
        </varlistentry>
      </variablelist>
      
    </sect2>
  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.advanced.props.special.ignore">
    <title>Ignoring Unversioned Items</title>

    <para>In any given working copy, there is a good chance that
      alongside all those versioned files and directories are other
      files and directories that are neither versioned nor intended
      to be.  Text editors litter directories with backup files.
      Software compilers generate intermediate&mdash;or even
      final&mdash;files that you typically wouldn't bother to
      version.  And users themselves drop various other files and
      directories wherever they see fit, often in version control
      working copies.</para>

    <para>It's ludicrous to expect Subversion working copies to be
      somehow impervious to this kind of clutter and impurity.  In
      fact, Subversion counts it as a <emphasis>feature</emphasis>
      that its working copies are just typical directories, just like
      unversioned trees.  But these not-to-be-versioned files and
      directories can cause some annoyance for Subversion users.  For
      example, because the <command>svn add</command> and <command>svn
      import</command> commands act recursively by default and don't
      know which files in a given tree you do and don't wish to
      version, it's easy to accidentally add stuff to version control
      that you didn't mean to.  And because <command>svn
      status</command> reports, by default, every item of interest in
      a working copy&mdash;including unversioned files and
      directories&mdash;its output can get quite noisy where many of
      these things exist.</para>

    <para>So Subversion provides two ways for telling it which files
      you would prefer that it simply disregard.  One of the ways
      involves the use of Subversion's runtime configuration system
      (see <xref linkend="svn.advanced.confarea" />), and therefore
      applies to all the Subversion operations that make use of that
      runtime configuration&mdash;generally those performed on a particular
      computer or by a particular user of a computer.  The other way
      makes use of Subversion's directory property support and is more
      tightly bound to the versioned tree itself, and therefore
      affects everyone who has a working copy of that tree.  Both of
      the mechanisms use <firstterm>file patterns</firstterm> (strings
      of literal and special wildcard characters used to match against
      filenames) to decide which files to ignore.</para>

    <para>The Subversion runtime configuration system provides an
      option, <literal>global-ignores</literal>, whose value is a
      whitespace-delimited collection of file patterns.  The
      Subversion client checks these patterns against the names of the
      files that are candidates for addition to version control, as
      well as to unversioned files that the <command>svn
      status</command> command notices.  If any file's name matches
      one of the patterns, Subversion will basically act as if the
      file didn't exist at all.  This is really useful for the kinds
      of files that you almost never want to version, such as editor
      backup files such as Emacs' <literal>*~</literal> and
      <literal>.*~</literal> files.</para>

    <sidebar>
      <title>File Patterns in Subversion</title>

      <para>File patterns (also called <firstterm>globs</firstterm> or
        <firstterm>shell wildcard patterns</firstterm>) are strings of
        characters that are intended to be matched against filenames,
        typically for the purpose of quickly selecting some subset of
        similar files from a larger grouping without having to
        explicitly name each file.  The patterns contain two types of
        characters:  regular characters, which are compared explicitly
        against potential matches, and special wildcard characters,
        which are interpreted differently for matching
        purposes.</para>

      <para>There are different types of file pattern syntaxes, but
        Subversion uses the one most commonly found in Unix systems
        implemented as the <function>fnmatch</function> system
        function.  It supports the following wildcards, described here
        simply for your convenience:</para>

      <variablelist>
        <varlistentry>
          <term><literal>?</literal></term>
          <listitem>
            <para>Matches any single character</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>*</literal></term>
          <listitem>
            <para>Matches any string of characters, including the
              empty string</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>[</literal></term>
          <listitem>
            <para>Begins a character class definition terminated by
              <literal>]</literal>, used for matching a subset of
              characters</para>
          </listitem>
        </varlistentry>
      </variablelist>


      <para>You can see this same pattern matching behavior at a Unix
        shell prompt.  The following are some examples of patterns
        being used for various things:</para>

      <screen>
$ ls   ### the book sources
appa-quickstart.xml             ch06-server-configuration.xml
appb-svn-for-cvs-users.xml      ch07-customizing-svn.xml
appc-webdav.xml                 ch08-embedding-svn.xml
book.xml                        ch09-reference.xml
ch00-preface.xml                ch10-world-peace-thru-svn.xml
ch01-fundamental-concepts.xml   copyright.xml
ch02-basic-usage.xml            foreword.xml
ch03-advanced-topics.xml        images/
ch04-branching-and-merging.xml  index.xml
ch05-repository-admin.xml       styles.css
$ ls ch*   ### the book chapters
ch00-preface.xml                ch06-server-configuration.xml
ch01-fundamental-concepts.xml   ch07-customizing-svn.xml
ch02-basic-usage.xml            ch08-embedding-svn.xml
ch03-advanced-topics.xml        ch09-reference.xml
ch04-branching-and-merging.xml  ch10-world-peace-thru-svn.xml
ch05-repository-admin.xml
$ ls ch?0-*   ### the book chapters whose numbers end in zero
ch00-preface.xml  ch10-world-peace-thru-svn.xml
$ ls ch0[3578]-*   ### the book chapters that Mike is responsible for
ch03-advanced-topics.xml   ch07-customizing-svn.xml
ch05-repository-admin.xml  ch08-embedding-svn.xml
$
</screen>

      <para>File pattern matching is a bit more complex than what
        we've described here, but this basic usage level tends to suit
        the majority of Subversion users.</para>

    </sidebar>

    <para>When found on a versioned directory, the
      <literal>svn:ignore</literal> property is expected to contain a
      list of newline-delimited file patterns that Subversion should
      use to determine ignorable objects in that same directory.
      These patterns do not override those found in the
      <literal>global-ignores</literal> runtime configuration option,
      but are instead appended to that list.  And it's worth noting
      again that, unlike the <literal>global-ignores</literal> option,
      the patterns found in the <literal>svn:ignore</literal>
      property apply only to the directory on which that property is
      set, and not to any of its subdirectories.  The
      <literal>svn:ignore</literal> property is a good way to tell
      Subversion to ignore files that are likely to be present in
      every user's working copy of that directory, such as compiler
      output or&mdash;to use an example more appropriate to this
      book&mdash;the HTML, PDF, or PostScript files generated as the
      result of a conversion of some source DocBook XML files to a
      more legible output format.</para>

    <note>
      <para>Subversion's support for ignorable file patterns extends
        only to the one-time process of adding unversioned
        files and directories to version control.  Once an object is
        under Subversion's control, the ignore pattern mechanisms no
        longer apply to it.  In other words, don't expect Subversion
        to avoid committing changes you've made to a versioned file
        simply because that file's name matches an ignore
        pattern&mdash;Subversion <emphasis>always</emphasis> notices
        all of its versioned objects.</para>
    </note>

    <sidebar>
      <title>Ignore Patterns for CVS Users</title>
    
      <para>The Subversion <literal>svn:ignore</literal> property is
        very similar in syntax and function to the CVS
        <filename>.cvsignore</filename> file.  In fact, if you are
        migrating a CVS working copy to Subversion, you can directly
        migrate the ignore patterns by using the
        <filename>.cvsignore</filename> file as input file to the
        <command>svn propset</command> command:</para>
   
      <screen>
$ svn propset svn:ignore -F .cvsignore .
property 'svn:ignore' set on '.'
$
</screen>        
    
      <para>There are, however, some differences in the ways that CVS
        and Subversion handle ignore patterns.  The two systems use
        the ignore patterns at some different times, and there are
        slight discrepancies in what the ignore patterns apply to.
        Also, Subversion does not recognize the use of the
        <literal>!</literal> pattern as a reset back to having no
        ignore patterns at all.</para>

    </sidebar>

    <para>The global list of ignore patterns tends to be more a
      matter of personal taste and ties more closely to a user's
      particular tool chain than to the details of any particular
      working copy's needs.  So, the rest of this section will focus
      on the <literal>svn:ignore</literal> property and its
      uses.</para>

    <para>Say you have the following output from <command>svn
      status</command>:</para>

    <screen>
$ svn status calc
 M     calc/button.c
?      calc/calculator
?      calc/data.c
?      calc/debug_log
?      calc/debug_log.1
?      calc/debug_log.2.gz
?      calc/debug_log.3.gz
</screen>
    
    <para>In this example, you have made some property modifications
      to <filename>button.c</filename>, but in your working copy, you
      also have some unversioned files: the latest
      <filename>calculator</filename> program that you've compiled
      from your source code, a source file named
      <filename>data.c</filename>, and a set of debugging output logfiles.
      Now, you know that your build system always results in
      the <filename>calculator</filename> program being generated.
      <footnote>
        <para>Isn't that the whole point of a build system?</para>
      </footnote>
      And you know that your test suite always leaves those debugging
      logfiles lying around.  These facts are true for all working
      copies of this project, not just your own.  And you know that
      you aren't interested in seeing those things every time you run
      <command>svn status</command>, and you are pretty sure that
      nobody else is interested in them either.  So you use
      <userinput>svn propedit svn:ignore calc</userinput> to add some
      ignore patterns to the <filename>calc</filename> directory.  For
      example, you might add this as the new value of the
      <literal>svn:ignore</literal> property:</para>

    <programlisting>
calculator
debug_log*
</programlisting>
    
    <para>After you've added this property, you will now have a local
      property modification on the <filename>calc</filename>
      directory.  But notice what else is different about your
      <command>svn status</command> output:</para>

    <screen>
$ svn status
 M     calc
 M     calc/button.c
?      calc/data.c
</screen>
    
    <para>Now, all that cruft is missing from the output!  Your
      <filename>calculator</filename> compiled program and all those
      logfiles are still in your working copy; Subversion just isn't
      constantly reminding you that they are present and unversioned.
      And now with all the uninteresting noise removed from the
      display, you are left with more intriguing items&mdash;such as
      that source code file <filename>data.c</filename> that you
      probably forgot to add to version control.</para>

    <para>Of course, this less-verbose report of your working copy
      status isn't the only one available.  If you actually want to
      see the ignored files as part of the status report, you can pass
      the <option>--no-ignore</option> option to Subversion:</para>

    <screen>
$ svn status --no-ignore
 M     calc
 M     calc/button.c
I      calc/calculator
?      calc/data.c
I      calc/debug_log
I      calc/debug_log.1
I      calc/debug_log.2.gz
I      calc/debug_log.3.gz
</screen>
    
    <para>As mentioned earlier, the list of file patterns to ignore is
      also used by <command>svn add</command> and <command>svn
      import</command>.  Both of these operations involve asking
      Subversion to begin managing some set of files and directories.
      Rather than force the user to pick and choose which files in a
      tree she wishes to start versioning, Subversion uses the ignore
      patterns&mdash;both the global and the per-directory
      lists&mdash;to determine which files should not be swept into
      the version control system as part of a larger recursive
      addition or import operation.  And here again, you can use the
      <option>--no-ignore</option> option to tell Subversion ignore
      its ignores list and operate on all the files and directories
      present.</para>

    <tip>
      <para>Even if <literal>svn:ignore</literal> is set, you may run
        into problems if you use shell wildcards in a command.  Shell
        wildcards are expanded into an explicit list of targets before
        Subversion operates on them, so running <userinput>svn
        <replaceable>SUBCOMMAND</replaceable> *</userinput> is just like
        running <userinput>svn <replaceable>SUBCOMMAND</replaceable>
        file1 file2 file3 &hellip;</userinput>.  In the case of the
        <command>svn add</command> command, this has an effect similar
        to passing the <option>--no-ignore</option> option.  So
        instead of using a wildcard, use <userinput>svn add --force
        .</userinput> to do a bulk scheduling of unversioned things for
        addition.  The explicit target will ensure that the current
        directory isn't overlooked because of being already under
        version control, and the <option>--force</option> option will
        cause Subversion to crawl through that directory, adding
        unversioned files while still honoring the
        <literal>svn:ignore</literal> property and
        <literal>global-ignores</literal> runtime configuration
        variable.  Be sure to also provide the <option>--depth
        files</option> option to the <command>svn add</command>
        command if you don't want a fully recursive crawl for things
        to add.</para>


      </tip>

  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.advanced.props.special.keywords">
    <title>Keyword Substitution</title>

    <para>Subversion has the ability to substitute
      <firstterm>keywords</firstterm>&mdash;pieces of useful,
      dynamic information about a versioned file&mdash;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
      <emphasis>after</emphasis> 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.</para>

    <para>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
      <literal>LastChangedDate</literal> keyword.  You control
      where the keyword is inserted into your document by placing
      a <firstterm>keyword anchor</firstterm> at the desired
      location in the file.  This anchor is just a string of text
      formatted as
      <literal>$</literal><replaceable>KeywordName</replaceable><literal>$</literal>.</para>

    <para>All keywords are case-sensitive where they appear as
      anchors in files: you must use the correct capitalization
      for the keyword to be expanded.  You should consider the
      value of the <literal>svn:keywords</literal> property to be
      case-sensitive, too&mdash;certain keyword names will be recognized
      regardless of case, but this behavior is deprecated.</para>

    <para>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:</para>

    <variablelist>
      <varlistentry>
        <term><literal>Date</literal></term>
        <listitem>
          <para>This keyword describes the last time the file was
            known to have been changed in the repository, and is of
            the form <literal>$Date: 2006-07-22 21:42:37 -0700 (Sat,
            22 Jul 2006) $</literal>.  It may also be specified as
            <literal>LastChangedDate</literal>.  Unlike the
            <literal>Id</literal> keyword, which uses UTC, the
            <literal>Date</literal> keyword displays dates using the
            local time zone.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><literal>Revision</literal></term>
        <listitem>
          <para>This keyword describes the last known revision in
            which this file changed in the repository, and looks
            something like <literal>$Revision: 144 $</literal>.  
            It may also be specified as
            <literal>LastChangedRevision</literal> or
            <literal>Rev</literal>.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><literal>Author</literal></term>
        <listitem>
          <para>This keyword describes the last known user to
            change this file in the repository, and looks
            something like <literal>$Author: harry $</literal>.  
            It may also be specified as 
            <literal>LastChangedBy</literal>.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><literal>HeadURL</literal></term>
        <listitem>
          <para>This keyword describes the full URL to the latest
            version of the file in the repository, and looks
            something like <literal>$HeadURL:
            http://svn.collab.net/repos/trunk/README $</literal>.
            It may be abbreviated as
            <literal>URL</literal>.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><literal>Id</literal></term>
        <listitem>
          <para>This keyword is a compressed combination of the other
            keywords.  Its substitution looks something like
            <literal>$Id: calc.c 148 2006-07-28 21:30:43Z sally
            $</literal>, and is interpreted to mean that the file
            <filename>calc.c</filename> was last changed in revision
            148 on the evening of July 28, 2006 by the user
            <literal>sally</literal>.  The date displayed by this
            keyword is in UTC, unlike that of the
            <literal>Date</literal> keyword (which uses the local time
            zone).</para>
        </listitem>
      </varlistentry>
    </variablelist>

    <para>Several of the preceding descriptions use the phrase
      <quote>last known</quote> or similar wording.  Keep in mind that
      keyword expansion is a client-side operation, and your client
      <quote>knows</quote> only about changes that 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.</para>

    <para>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
      <footnote>
        <para>&hellip; or maybe even a section of a book &hellip;</para>
      </footnote> 
      about how to use keywords, and you don't want Subversion to
      substitute your beautiful examples of unsubstituted keyword
      anchors!</para>

    <para>To tell Subversion whether to substitute keywords
      on a particular file, we again turn to the property-related
      subcommands.  The <literal>svn:keywords</literal> property,
      when set on a versioned file, controls which keywords will
      be substituted on that file.  The value is a space-delimited
      list of keyword names or aliases.</para>

    <para>For example, say you have a versioned file named
      <filename>weather.txt</filename> that looks like
      this:</para>

    <programlisting>
Here is the latest report from the front lines.
$LastChangedDate$
$Rev$
Cumulus clouds are appearing more frequently as summer approaches.
</programlisting>
        
    <para>With no <literal>svn:keywords</literal> property set on
      that file, Subversion will do nothing special.  Now, let's
      enable substitution of the
      <literal>LastChangedDate</literal> keyword.</para>

    <screen>
$ svn propset svn:keywords "Date Author" weather.txt
property 'svn:keywords' set on 'weather.txt'
$
</screen>        
    
    <para>Now you have made a local property modification on the
      <filename>weather.txt</filename> 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 <literal>Rev</literal>
      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
      <literal>svn:keywords</literal> property value.</para>

    <para>Immediately after you commit this property change,
      Subversion will update your working file with the new
      substitute text.  Instead of seeing your keyword anchor
      <literal>$LastChangedDate$</literal>, you'll see its
      substituted result.  That result also contains the name of
      the keyword and continues to be delimited by the dollar sign
      (<literal>$</literal>) characters.  And as we predicted, the
      <literal>Rev</literal> keyword was not substituted because
      we didn't ask for it to be.</para>

    <para>Note also that we set the <literal>svn:keywords</literal>
      property to <literal>Date Author</literal>, yet the keyword
      anchor used the alias <literal>$LastChangedDate$</literal>
      and still expanded correctly:</para>

    <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.
</screen>
        
    <para>If someone else now commits a change to
      <filename>weather.txt</filename>, your copy of that file
      will continue to display the same substituted keyword value
      as before&mdash;until you update your working copy.  At that
      time, the keywords in your <filename>weather.txt</filename>
      file will be resubstituted with information that
      reflects the most recent known commit to that file.</para>


    <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 it is this number that 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&mdash;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.  It 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 <command>svnversion</command>, see <xref
        linkend="svn.ref.svnversion"/>.</para>

    </sidebar>

    <para>Subversion 1.2 introduced a new variant of the keyword
      syntax, which brought additional, useful&mdash;though perhaps
      atypical&mdash;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 (<literal>::</literal>) 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 (<literal>#</literal>) character just before
      the final dollar sign terminator.</para>

    <para>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:</para>

    <screen>
$Rev$:     Revision of last commit
$Author$:  Author of last commit
$Date$:    Date of last commit
</screen>
    
    <para>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:</para>

    <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
</screen>
    
    <para>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 holds only 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 later, you can use the new
      fixed-length keyword syntax and define some field widths that
      seem sane, so your file might look like this:</para>

    <screen>
$Rev::               $:  Revision of last commit
$Author::            $:  Author of last commit
$Date::              $:  Date of last commit
</screen>
    
    <para>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&mdash;the short values for
      <literal>Rev</literal> and <literal>Author</literal> are
      padded with spaces, and the long <literal>Date</literal>
      field is truncated by a hash character:</para>

    <screen>
$Rev:: 13            $:  Revision of last commit
$Author:: harry      $:  Author of last commit
$Date:: 2006-03-15 0#$:  Date of last commit
</screen>
       
    <para>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).</para>

    <warning>
      <para>Be aware that because the width of a keyword field is
        measured in bytes, the potential for corruption of
        multibyte values exists.  For example, a username that
        contains some multibyte UTF-8 characters might suffer
        truncation in the middle of the string of bytes that 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.</para> 
    </warning>

  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.advanced.sparsedirs">
    <title>Sparse Directories</title>

    <para>By default, most Subversion operations on directories act in
      a recursive manner.  For example, <command>svn
      checkout</command> creates a working copy with every file and
      directory in the specified area of the repository, descending
      recursively through the repository tree until the entire
      structure is copied to your local disk.  Subversion 1.5
      introduces a feature called <firstterm>sparse
      directories</firstterm> (or <firstterm>shallow
      checkouts</firstterm>) that allows you to easily check out a
      working copy&mdash;or a portion of a working copy&mdash;more
      shallowly than full recursion, with the freedom to bring in
      previously ignored files and subdirectories at a later
      time.</para>

    <para>For example, say we have a repository with a tree of files
      and directories with names of the members of a human family with
      pets.  (It's an odd example, to be sure, but bear with us.)  A
      regular <command>svn checkout</command> operation will give us a
      working copy of the whole tree:</para>

    <screen>
$ svn checkout file:///var/svn/repos mom
A    mom/son
A    mom/son/grandson
A    mom/daughter
A    mom/daughter/granddaughter1
A    mom/daughter/granddaughter1/bunny1.txt
A    mom/daughter/granddaughter1/bunny2.txt
A    mom/daughter/granddaughter2
A    mom/daughter/fishie.txt
A    mom/kitty1.txt
A    mom/doggie1.txt
Checked out revision 1.
$
</screen>

    <para>Now, let's check out the same tree again, but this time
      we'll ask Subversion to give us only the topmost directory
      with none of its children at all:</para>

    <screen>
$ svn checkout file:///var/svn/repos mom-empty --depth empty
Checked out revision 1
$
</screen>
 
    <para>Notice that we added to our original <command>svn
      checkout</command> command line a new <option>--depth</option>
      option.  This option is present on many of Subversion's
      subcommands and is similar to the
      <option>--non-recursive</option> (<option>-N</option>) and
      <option>--recursive</option> (<option>-R</option>) options.  In
      fact, it combines, improves upon, supercedes, and ultimately
      obsoletes these two older options.  For starters, it expands the
      supported degrees of depth specification available to users,
      adding some previously unsupported (or inconsistently supported)
      depths.  Here are the depth values that you can request for a
      given Subversion operation:</para>

    <variablelist>