ch03-advanced-topics.xml - svnbook - Version Control With Subversion

Source path: svn/ tags/ en-1.5-final/ src/ en/ book/ ch03-advanced-topics.xml

‹r3305

r4266

<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>

    <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, "Do you have the
          property I'm looking for?"  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 "Name".</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>

      <varlistentry>
        <term><literal>--depth empty</literal></term>
        <listitem>
          <para>Include only the immediate target of the operation,
            not any of its file or directory children.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>--depth files</literal></term>
        <listitem>
          <para>Include the immediate target of the operation and any
            of its immediate file children.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><literal>--depth immediates</literal></term>
        <listitem>
          <para>Include the immediate target of the operation and any
            of its immediate file or directory children.  The directory
            children will themselves be empty.</para>
        </listitem>
      </varlistentry>
      
      <varlistentry>
        <term><literal>--depth infinity</literal></term>
        <listitem>
          <para>Include the immediate target, its file and directory
            children, its children's children, and so on to full
            recursion.</para>
        </listitem>
      </varlistentry>

    </variablelist>

    <para>Of course, merely combining two existing options into one
      hardly constitutes a new feature worthy of a whole section in
      our book.  Fortunately, there is more to this story.  This idea
      of depth extends not just to the operations you perform with
      your Subversion client, but also as a description of a working
      copy citizen's <firstterm>ambient depth</firstterm>, which is
      the depth persistently recorded by the working copy for that
      item.  Its key strength is this very persistence&mdash;the fact
      that it is <firstterm>sticky</firstterm>.  The working copy
      remembers the depth you've selected for each item in it until
      you later change that depth selection; by default, Subversion
      commands operate on the working copy citizens present,
      regardless of their selected depth settings.</para>

    <tip>
      <para>You can check the recorded ambient depth of a working copy
        using the <command>svn info</command> command.  If the ambient
        depth is anything other than infinite recursion, <command>svn
        info</command> will display a line describing that depth
        value:</para>

      <screen>
$ svn info mom-immediates | grep '^Depth:'
Depth: immediates
$
</screen>
    </tip>

    <para>Our previous examples demonstrated checkouts of infinite
      depth (the default for <command>svn checkout</command>) and
      empty depth.  Let's look now at examples of the other depth
      values:</para>

    <screen>
$ svn checkout file:///var/svn/repos mom-files --depth files
A    mom-files/kitty1.txt
A    mom-files/doggie1.txt
Checked out revision 1.
$ svn checkout file:///var/svn/repos mom-immediates --depth immediates
A    mom-immediates/son
A    mom-immediates/daughter
A    mom-immediates/kitty1.txt
A    mom-immediates/doggie1.txt
Checked out revision 1.
$
</screen>

    <para>As described, each of these depths is something more than
      only the target, but something less than full recursion.</para>

    <para>We've used <command>svn checkout</command> as an example
      here, but you'll find the <option>--depth</option> option
      present on many other Subversion commands, too.  In those other
      commands, depth specification is a way to limit the scope of an
      operation to some depth, much like the way the older
      <option>--non-recursive</option> (<option>-N</option>) and
      <option>--recursive</option> (<option>-R</option>) options
      behave.  This means that when operating on a working copy of
      some depth, while requesting an operation of a shallower depth,
      the operation is limited to that shallower depth.  In fact, we
      can make an even more general statement: given a working copy of
      any arbitrary&mdash;even mixed&mdash;ambient depth, and a
      Subversion command with some requested operational depth, the
      command will maintain the ambient depth of the working copy
      members while still limiting the scope of the operation to the
      requested (or default) operational depth.</para>

    <para>In addition to the <option>--depth</option> option, the
      <command>svn update</command> and <command>svn switch</command>
      subcommands also accept a second depth-related option:
      <option>--set-depth</option>.  It is with this option that you
      can change the sticky depth of a working copy item.  Watch what
      happens as we take our empty-depth checkout and gradually
      telescope it deeper using <userinput>svn update
      --set-depth <replaceable>NEW-DEPTH</replaceable> <replaceable>TARGET</replaceable></userinput>:</para>

    <screen>
$ svn update --set-depth files mom-empty
A    mom-empty/kittie1.txt
A    mom-empty/doggie1.txt
Updated to revision 1.
$ svn update --set-depth immediates mom-empty
A    mom-empty/son
A    mom-empty/daughter
Updated to revision 1.
$ svn update --set-depth infinity mom-empty
A    mom-empty/son/grandson
A    mom-empty/daughter/granddaughter1
A    mom-empty/daughter/granddaughter1/bunny1.txt
A    mom-empty/daughter/granddaughter1/bunny2.txt
A    mom-empty/daughter/granddaughter2
A    mom-empty/daughter/fishie1.txt
Updated to revision 1.
$
</screen>

    <para>As we gradually increased our depth selection, the
      repository gave us more pieces of our tree.</para>

    <para>In our example, we operated only on the root of our working
      copy, changing its ambient depth value.  But we can
      independently change the ambient depth value of
      <emphasis>any</emphasis> subdirectory inside the working copy,
      too.  Careful use of this ability allows us to flesh out only
      certain portions of the working copy tree, leaving other
      portions absent altogether (hence the <quote>sparse</quote> bit
      of the feature's name).  Here's an example of how we might build
      out a portion of one branch of our family's tree, enable full
      recursion on another branch, and keep still other pieces pruned
      (absent from disk).</para>

    <screen>
$ rm -rf mom-empty
$ svn checkout file:///var/svn/repos mom-empty --depth empty
Checked out revision 1.
$ svn update --set-depth empty mom-empty/son
A    mom-empty/son
Updated to revision 1.
$ svn update --set-depth empty mom-empty/daughter
A    mom-empty/daughter
Updated to revision 1.
$ svn update --set-depth infinity mom-empty/daughter/granddaughter1
A    mom-empty/daughter/granddaughter1
A    mom-empty/daughter/granddaughter1/bunny1.txt
A    mom-empty/daughter/granddaughter1/bunny2.txt
Updated to revision 1.
$
</screen>

    <para>Fortunately, having a complex collection of ambient depths
      in a single working copy doesn't complicate the way you interact
      with that working copy.  You can still make, revert, display,
      and commit local modifications in your working copy without
      providing any new options (including <option>--depth</option> and
      <option>--set-depth</option>) to the relevant subcommands.  Even
      <command>svn update</command> works as it does elsewhere when no
      specific depth is provided&mdash;it updates the working copy
      targets that are present while honoring their sticky
      depths.</para>

    <para>You might at this point be wondering, <quote>So what?  When
      would I use this?</quote>  One scenario where this feature
      finds utility is tied to a particular repository layout,
      specifically where you have many related or codependent
      projects or software modules living as siblings in a single
      repository location (<filename>trunk/project1</filename>,
      <filename>trunk/project2</filename>,
      <filename>trunk/project3</filename>, etc.).  In such
      scenarios, it might be the case that you personally care 
      about only a handful of those projects&mdash;maybe some primary
      project and a few other modules on which it depends.  You can
      check out individual working copies of all of these things, but
      those working copies are disjoint and, as a result, it can be
      cumbersome to perform operations across several or all of them
      at the same time.  The alternative is to use the sparse
      directories feature, building out a single working copy that
      contains only the modules you care about.  You'd start with an
      empty-depth checkout of the common parent directory of the
      projects, and then update with infinite depth only the items you
      wish to have, like we demonstrated in the previous example.
      Think of it like an opt-in system for working copy
      citizens.</para>

    <para>Subversion 1.5's implementation of shallow checkouts is
      good but does not support a couple of interesting behaviors.
      First, you cannot de-telescope a working copy item.  Running
      <userinput>svn update --set-depth empty</userinput> in an
      infinite-depth working copy will not have the effect of
      discarding everything but the topmost directory&mdash;it will
      simply error out.  Second, there is no depth value to indicate
      that you wish an item to be explicitly excluded.  You have to do
      implicit exclusion of an item by including everything
      else.</para>

  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.advanced.locking">
    <title>Locking</title>

    <para>Subversion's copy-modify-merge version control model lives
      and dies on its data merging algorithms&mdash;specifically on
      how well those algorithms perform when trying to resolve
      conflicts caused by multiple users modifying the same file
      concurrently.  Subversion itself provides only one such
      algorithm:  a three-way differencing algorithm that is smart
      enough to handle data at a granularity of a single line of text.
      Subversion also allows you to supplement its content merge
      processing with external differencing utilities (as described in
      <xref linkend="svn.advanced.externaldifftools.diff3" />), some
      of which may do an even better job, perhaps providing
      granularity of a word or a single character of text.  But common
      among those algorithms is that they generally work only on text
      files.  The landscape starts to look pretty grim when you start
      talking about content merges of nontextual file formats.  And
      when you can't find a tool that can handle that type of merging,
      you begin to run into problems with the copy-modify-merge
      model.</para>

   <para>Let's look at a real-life example of where this model runs
      aground.  Harry and Sally are both graphic designers working on
      the same project, a bit of marketing collateral for an
      automobile mechanic.  Central to the design of a particular
      poster is an image of a car in need of some bodywork, stored in
      a file using the PNG image format.  The poster's layout is
      almost finished, and both Harry and Sally are pleased with the
      particular photo they chose for their damaged car&mdash;a baby
      blue 1967 Ford Mustang with an unfortunate bit of crumpling on
      the left front fender.</para>

    <para>Now, as is common in graphic design work, there's a change
      in plans, which causes the car's color to be a concern.  So Sally
      updates her working copy to <literal>HEAD</literal>, fires up
      her photo-editing software, and sets about tweaking the image so
      that the car is now cherry red.  Meanwhile, Harry, feeling
      particularly inspired that day, decides that the image would
      have greater impact if the car also appears to have suffered
      greater impact.  He, too, updates to <literal>HEAD</literal>,
      and then draws some cracks on the vehicle's windshield.  He
      manages to finish his work before Sally finishes hers, and after
      admiring the fruits of his undeniable talent, he commits the
      modified image.  Shortly thereafter, Sally is finished with the
      car's new finish and tries to commit her changes.  But, as
      expected, Subversion fails the commit, informing Sally that
      her version of the image is now out of date.</para>

    <para>Here's where the difficulty sets in.  If Harry and Sally
      were making changes to a text file, Sally would simply update
      her working copy, receiving Harry's changes in the process.  In
      the worst possible case, they would have modified the same
      region of the file, and Sally would have to work out by hand the
      proper resolution to the conflict.  But these aren't text
      files&mdash;they are binary images.  And while it's a simple
      matter to describe what one would expect the results of this
      content merge to be, there is precious little chance that any
      software exists that is smart enough to examine the common
      baseline image that each of these graphic artists worked
      against, the changes that Harry made, and the changes that Sally
      made, and then spit out an image of a busted-up red Mustang with
      a cracked windshield!</para>

    <para>Of course, things would have gone more smoothly if Harry and
      Sally had serialized their modifications to the image&mdash;if, say,
      Harry had waited to draw his windshield cracks on Sally's
      now-red car, or if Sally had tweaked the color of a car whose
      windshield was already cracked.  As is discussed in <xref
      linkend="svn.basic.vsn-models.copy-merge" />, most of these
      types of problems go away entirely where perfect communication
      between Harry and Sally exists.
      <footnote>
        <para>Communication wouldn't have been such bad medicine for
          Harry and Sally's Hollywood namesakes, either, for that
          matter.</para>
      </footnote>
      But as one's version control system is, in fact, one form of
      communication, it follows that having that software facilitate
      the serialization of nonparallelizable editing efforts is no
      bad thing.  This is where Subversion's implementation of the
      lock-modify-unlock model steps into the spotlight.  This is
      where we talk about Subversion's <firstterm>locking</firstterm>
      feature, which is similar to the <quote>reserved
      checkouts</quote> mechanisms of other version control
      systems.</para>

    <para>Subversion's locking feature exists ultimately to minimize
      wasted time and effort.  By allowing a user to programmatically
      claim the exclusive right to change a file in the repository,
      that user can be reasonably confident that any energy he invests
      on unmergeable changes won't be wasted&mdash;his commit of those
      changes will succeed.  Also, because Subversion communicates to
      other users that serialization is in effect for a particular
      versioned object, those users can reasonably expect that the
      object is about to be changed by someone else.  They, too, can
      then avoid wasting their time and energy on unmergeable changes
      that won't be committable due to eventual
      out-of-dateness.</para>

    <para>When referring to Subversion's locking feature, one is
      actually talking about a fairly diverse collection of behaviors,
      which include the ability to lock a versioned file
      <footnote>
        <para>Subversion does not currently allow locks on directories.</para>
      </footnote>
      (claiming the exclusive right to modify the file), to unlock
      that file (yielding that exclusive right to modify), to see
      reports about which files are locked and by whom, to annotate
      files for which locking before editing is strongly advised, and
      so on.  In this section, we'll cover all of these facets of the
      larger locking feature.</para>

    <sidebar id="svn.advanced.locking.meanings">
      <title>The Three Meanings of <quote>Lock</quote></title>

      <para>In this section, and almost everywhere in this book, the
        words <quote>lock</quote> and <quote>locking</quote> describe
        a mechanism for mutual exclusion between users to avoid
        clashing commits.  Unfortunately, there are two other sorts
        of <quote>lock</quote> with which Subversion, and therefore
        this book, sometimes needs to be concerned.</para>

      <para>The second is <firstterm>working copy locks</firstterm>,
        used internally by Subversion to prevent clashes between
        multiple Subversion clients operating on the same working
        copy.  This is the sort of lock indicated by an
        <computeroutput>L</computeroutput> in the third column of
        <command>svn status</command> output, and removed by the
        <command>svn cleanup</command> command, as described in <xref
        linkend="svn.tour.cleanup"/>.</para>

      <para>Third, there are <firstterm>database locks</firstterm>,
        used internally by the Berkeley DB backend to prevent clashes
        between multiple programs trying to access the database.  This
        is the sort of lock whose unwanted persistence after an error
        can cause a repository to be <quote>wedged,</quote> as
        described in <xref linkend="svn.reposadmin.maint.recovery"
        />.</para>

      <para>You can generally forget about these other kinds of locks
        until something goes wrong that requires you to care about
        them.  In this book, <quote>lock</quote> means the first sort
        unless the contrary is either clear from context or explicitly
        stated.</para>

    </sidebar>

    <!-- =============================================================== -->
    <sect2 id="svn.advanced.locking.creation">
      <title>Creating Locks</title>
      
      <para>In the Subversion repository, a
        <firstterm>lock</firstterm> is a piece of metadata that
        grants exclusive access to one user to change a file.  This
        user is said to be the <firstterm>lock owner</firstterm>.
        Each lock also has a unique identifier, typically a long
        string of characters, known as the <firstterm>lock
        token</firstterm>.  The repository manages locks, ultimately
        handling their creation, enforcement, and removal.  If any
        commit transaction attempts to modify or delete a locked file
        (or delete one of the parent directories of the file), the
        repository will demand two pieces of information&mdash;that
        the client performing the commit be authenticated as the lock
        owner, and that the lock token has been provided as part of
        the commit process as a form of proof that the client knows which
        lock it is using.</para>
      
      <para>To demonstrate lock creation, let's refer back to our
        example of multiple graphic designers working on the same
        binary image files.  Harry has decided to change a JPEG image.
        To prevent other people from committing changes to the file
        while he is modifying it (as well as alerting them that he is
        about to change it), he locks the file in the repository using
        the <command>svn lock</command> command.</para>

      <screen>
$ svn lock banana.jpg -m "Editing file for tomorrow's release."
'banana.jpg' locked by user 'harry'.
$
</screen>

      <para>The preceding example demonstrates a number of new things.
        First, notice that Harry passed the
        <option>--message</option> (<option>-m</option>) option to
        <command>svn lock</command>.  Similar to <command>svn
        commit</command>, the <command>svn lock</command> command can
        take comments&mdash;via either <option>--message</option>
        (<option>-m</option>) or <option>--file</option>
        (<option>-F</option>)&mdash;to describe the reason for locking the
        file.  Unlike <command>svn commit</command>, however,
        <command>svn lock</command> will not demand a message by
        launching your preferred text editor.  Lock comments are
        optional, but still recommended to aid communication.</para>

      <para>Second, the lock attempt succeeded.  This means that the
        file wasn't already locked, and that Harry had the latest
        version of the file.  If Harry's working copy of the file had
        been out of date, the repository would have rejected the
        request, forcing Harry to <command>svn update</command> and
        reattempt the locking command.  The locking command would also
        have failed if the file had already been locked by someone
        else.</para>

      <para>As you can see, the <command>svn lock</command> command
        prints confirmation of the successful lock.  At this point,
        the fact that the file is locked becomes apparent in the
        output of the <command>svn status</command> and <command>svn
        info</command> reporting subcommands.</para>

      <screen>
$ svn status
     K banana.jpg

$ svn info banana.jpg
Path: banana.jpg
Name: banana.jpg
URL: http://svn.example.com/repos/project/banana.jpg
Repository UUID: edb2f264-5ef2-0310-a47a-87b0ce17a8ec
Revision: 2198
Node Kind: file
Schedule: normal
Last Changed Author: frank
Last Changed Rev: 1950
Last Changed Date: 2006-03-15 12:43:04 -0600 (Wed, 15 Mar 2006)
Text Last Updated: 2006-06-08 19:23:07 -0500 (Thu, 08 Jun 2006)
Properties Last Updated: 2006-06-08 19:23:07 -0500 (Thu, 08 Jun 2006)
Checksum: 3b110d3b10638f5d1f4fe0f436a5a2a5
Lock Token: opaquelocktoken:0c0f600b-88f9-0310-9e48-355b44d4a58e
Lock Owner: harry
Lock Created: 2006-06-14 17:20:31 -0500 (Wed, 14 Jun 2006)
Lock Comment (1 line):
Editing file for tomorrow's release.

$
</screen>

      <para>The fact that the <command>svn info</command> command,
        which does not contact the repository when run against working
        copy paths, can display the lock token reveals an important
        piece of information about those tokens:  they are cached in
        the working copy.  The presence of the lock token is critical.
        It gives the working copy authorization to make use of the
        lock later on.  Also, the <command>svn status</command>
        command shows a <literal>K</literal> next to the file (short
        for locKed), indicating that the lock token is present.</para>

      <sidebar>
        <title>Regarding Lock Tokens</title>

        <para>A lock token isn't an authentication token, so much as
          an <emphasis>authorization</emphasis> token.  The token
          isn't a protected secret.  In fact, a lock's unique token is
          discoverable by anyone who runs <userinput>svn info
          <replaceable>URL</replaceable></userinput>.  A lock token is special only when it lives
          inside a working copy.  It's proof that the lock was created
          in that particular working copy, and not somewhere else by
          some other client.  Merely authenticating as the lock owner
          isn't enough to prevent accidents.</para>

        <para>For example, suppose you lock a file using a computer at
          your office, but leave work for the day before you finish
          your changes to that file.  It should not be possible to
          accidentally commit changes to that same file from your home
          computer later that evening simply because you've
          authenticated as the lock's owner.  In other words, the lock
          token prevents one piece of Subversion-related software from
          undermining the work of another.  (In our example, if you
          really need to change the file from an alternative working
          copy, you would need to <firstterm>break</firstterm> the lock and relock the
          file.)</para>

      </sidebar>

      <para>Now that Harry has locked <filename>banana.jpg</filename>,
        Sally is unable to change or delete that file:</para>

      <screen>
$ svn delete banana.jpg
D         banana.jpg
$ svn commit -m "Delete useless file."
Deleting       banana.jpg
svn: Commit failed (details follow):
svn: Server sent unexpected return value (423 Locked) in response to DELETE\
 request for '/repos/project/!svn/wrk/64bad3a9-96f9-0310-818a-df4224ddc35d/\
banana.jpg'
$
</screen>

      <para>But Harry, after touching up the banana's shade of yellow,
        is able to commit his changes to the file.  That's because he
        authenticates as the lock owner and also because his working
        copy holds the correct lock token:</para>

      <screen>
$ svn status
M    K banana.jpg
$ svn commit -m "Make banana more yellow"
Sending        banana.jpg
Transmitting file data .
Committed revision 2201.
$ svn status
$
</screen>

      <para>Notice that after the commit is finished, <command>svn
        status</command> shows that the lock token is no longer
        present in the working copy.  This is the standard behavior of
        <command>svn commit</command>&mdash;it searches the working
        copy (or list of targets, if you provide such a list) for
        local modifications and sends all the lock tokens it
        encounters during this walk to the server as part of the
        commit transaction.  After the commit completes successfully,
        all of the repository locks that were mentioned are
        released&mdash;<emphasis>even on files that weren't
        committed</emphasis>.  This is meant to discourage users from
        being sloppy about locking or from holding locks for too long.
        If Harry haphazardly locks 30 files in a directory named
        <filename>images</filename> because he's unsure of which files
        he needs to change, yet changes only four of those files, when he
        runs <userinput>svn commit images</userinput>, the process will
        still release all 30 locks.</para>

      <para>This behavior of automatically releasing locks can be
        overridden with the <option>--no-unlock</option> option to
        <command>svn commit</command>.  This is best used for those
        times when you want to commit changes, but still plan to make
        more changes and thus need to retain existing locks.  You can
        also make this your default behavior by setting the
        <literal>no-unlock</literal> runtime configuration option (see
        <xref linkend="svn.advanced.confarea" />).</para>

      <para>Of course, locking a file doesn't oblige one to commit a
        change to it.  The lock can be released at any time with a
        simple <command>svn unlock</command> command:</para>

      <screen>
$ svn unlock banana.c
'banana.c' unlocked.
</screen>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.advanced.locking.discovery">
      <title>Discovering Locks</title>

      <para>When a commit fails due to someone else's locks, it's
        fairly easy to learn about them.  The easiest way is to run
        <userinput>svn status --show-updates</userinput>:</para>

      <screen>
$ svn status -u
M              23   bar.c
M    O         32   raisin.jpg
       *       72   foo.h
Status against revision:     105
$
</screen>

      <para>In this example, Sally can see not only that her copy of
        <filename>foo.h</filename> is out of date, but also that one of the
        two modified files she plans to commit is locked in the
        repository.  The <literal>O</literal> symbol stands for
        <quote>Other,</quote> meaning that a lock exists on the file
        and was created by somebody else.  If she were to attempt a
        commit, the lock on <filename>raisin.jpg</filename> would
        prevent it.  Sally is left wondering who made the lock, when,
        and why.  Once again, <command>svn info</command> has the
        answers:</para>

      <screen>
$ svn info http://svn.example.com/repos/project/raisin.jpg
Path: raisin.jpg
Name: raisin.jpg
URL: http://svn.example.com/repos/project/raisin.jpg
Repository UUID: edb2f264-5ef2-0310-a47a-87b0ce17a8ec
Revision: 105
Node Kind: file
Last Changed Author: sally
Last Changed Rev: 32
Last Changed Date: 2006-01-25 12:43:04 -0600 (Sun, 25 Jan 2006)
Lock Token: opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b
Lock Owner: harry
Lock Created: 2006-02-16 13:29:18 -0500 (Thu, 16 Feb 2006)
Lock Comment (1 line):
Need to make a quick tweak to this image.
$
</screen>

      <para>Just as you can use <command>svn info</command> to examine
        objects in the working copy, you can also use it to examine
        objects in the repository.  If the main argument to
        <command>svn info</command> is a working copy path, then all
        of the working copy's cached information is displayed; any
        mention of a lock means that the working copy is holding a
        lock token (if a file is locked by another user or in another
        working copy, <command>svn info</command> on a working copy
        path will show no lock information at all).  If the main
        argument to <command>svn info</command> is a URL, the
        information reflects the latest version of an object in the
        repository, and any mention of a lock describes the current
        lock on the object.</para>

      <para>So in this particular example, Sally can see that Harry
        locked the file on February 16 to <quote>make a quick
        tweak.</quote>  It being June, she suspects that he probably
        forgot all about the lock.  She might phone Harry to complain
        and ask him to release the lock.  If he's unavailable, she
        might try to forcibly break the lock herself or ask an
        administrator to do so.</para>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.advanced.locking.break-steal">
      <title>Breaking and Stealing Locks</title>

      <para>A repository lock isn't sacred&mdash;in Subversion's
        default configuration state, locks can be released not only by
        the person who created them, but by anyone.  When somebody
        other than the original lock creator destroys a lock, we refer
        to this as <firstterm>breaking the lock</firstterm>.</para>

      <para>From the administrator's chair, it's simple to break
        locks.  The <command>svnlook</command>
        and <command>svnadmin</command> programs have the ability to
        display and remove locks directly from the repository.  (For
        more information about these tools, see
        <xref linkend="svn.reposadmin.maint.tk"/>.)</para>

      <screen>
$ svnadmin lslocks /var/svn/repos
Path: /project2/images/banana.jpg
UUID Token: opaquelocktoken:c32b4d88-e8fb-2310-abb3-153ff1236923
Owner: frank
Created: 2006-06-15 13:29:18 -0500 (Thu, 15 Jun 2006)
Expires: 
Comment (1 line):
Still improving the yellow color.

Path: /project/raisin.jpg
UUID Token: opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b
Owner: harry
Created: 2006-02-16 13:29:18 -0500 (Thu, 16 Feb 2006)
Expires: 
Comment (1 line):
Need to make a quick tweak to this image.

$ svnadmin rmlocks /var/svn/repos /project/raisin.jpg
Removed lock on '/project/raisin.jpg'.
$
</screen>

      <para>The more interesting option is to allow users to break
        each other's locks over the network.  To do this, Sally simply
        needs to pass the <option>--force</option> to the <command>svn
        unlock</command> command:</para>

      <screen>
$ svn status -u
M              23   bar.c
M    O         32   raisin.jpg
       *       72   foo.h
Status against revision:     105
$ svn unlock raisin.jpg
svn: 'raisin.jpg' is not locked in this working copy
$ svn info raisin.jpg | grep URL
URL: http://svn.example.com/repos/project/raisin.jpg
$ svn unlock http://svn.example.com/repos/project/raisin.jpg
svn: Unlock request failed: 403 Forbidden (http://svn.example.com)
$ svn unlock --force http://svn.example.com/repos/project/raisin.jpg
'raisin.jpg' unlocked.
$
</screen>

      <para>Now, Sally's initial attempt to unlock failed because she
        ran <command>svn unlock</command> directly on her working copy
        of the file, and no lock token was present.  To remove the
        lock directly from the repository, she needs to pass a URL
        to <command>svn unlock</command>.  Her first attempt to unlock
        the URL fails, because she can't authenticate as the lock
        owner (nor does she have the lock token).  But when she
        passes <option>--force</option>, the authentication and
        authorization requirements are ignored, and the remote lock is
        broken.</para>
        
      <para>Simply breaking a lock may not be enough.  In
        the running example, Sally may not only want to break Harry's
        long-forgotten lock, but relock the file for her own use.
        She can accomplish this by using <command>svn unlock</command>
        with <option>--force</option> and then <command>svn lock</command>
        back-to-back, but there's a small chance that somebody else
        might lock the file between the two commands.  The simpler thing
        to do is to <firstterm>steal</firstterm> the lock, which involves
        breaking and relocking the file all in one atomic step.  To
        do this, Sally passes the <option>--force</option> option
        to <command>svn lock</command>:</para>

      <screen>
$ svn lock raisin.jpg
svn: Lock request failed: 423 Locked (http://svn.example.com)
$ svn lock --force raisin.jpg
'raisin.jpg' locked by user 'sally'.
$
</screen>

      <para>In any case, whether the lock is broken or stolen, Harry
        may be in for a surprise.  Harry's working copy still contains
        the original lock token, but that lock no longer exists.  The
        lock token is said to be <firstterm>defunct</firstterm>.  The
        lock represented by the lock token has either been broken (no
        longer in the repository) or stolen (replaced with a
        different lock).  Either way, Harry can see this by asking
        <command>svn status</command> to contact the
        repository:</para>

      <screen>
$ svn status
     K raisin.jpg
$ svn status -u
     B         32   raisin.jpg
$ svn update
  B  raisin.jpg
$ svn status
$
</screen>

      <para>If the repository lock was broken, then <userinput>svn
        status --show-updates</userinput> displays a
        <literal>B</literal> (Broken) symbol next to the file.  If a
        new lock exists in place of the old one, then a
        <literal>T</literal> (sTolen) symbol is shown.  Finally,
        <command>svn update</command> notices any defunct lock tokens
        and removes them from the working copy.</para>

      <sidebar>
        <title>Locking Policies</title>
        
        <para>Different systems have different notions of how strict a
          lock should be.  Some folks argue that locks must be
          strictly enforced at all costs, releasable only by the
          original creator or administrator.  They argue that if
          anyone can break a lock, chaos runs rampant and the
          whole point of locking is defeated.  The other side argues
          that locks are first and foremost a communication tool.  If
          users are constantly breaking each other's locks, it
          represents a cultural failure within the team and the
          problem falls outside the scope of software enforcement.</para>

        <para>Subversion defaults to the <quote>softer</quote>
          approach, but still allows administrators to create stricter
          enforcement policies through the use of hook scripts.  In
          particular, the <filename>pre-lock</filename> and
          <filename>pre-unlock</filename> hooks allow administrators
          to decide when lock creation and lock releases are allowed
          to happen.  Depending on whether a lock already exists,
          these two hooks can decide whether to allow a certain user
          to break or steal a lock.  The
          <filename>post-lock</filename> and
          <filename>post-unlock</filename> hooks are also available,
          and can be used to send email after locking actions.  To
          learn more about repository hooks, see <xref
          linkend="svn.reposadmin.create.hooks" />.</para>

      </sidebar>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.advanced.locking.lock-communication">
      <title>Lock Communication</title>

      <para>We've seen how <command>svn lock</command>
        and <command>svn unlock</command> can be used to create,
        release, break, and steal locks.  This satisfies the goal of
        serializing commit access to a file.  But what about the
        larger problem of preventing wasted time?</para>

      <para>For example, suppose Harry locks an image file and then
        begins editing it.  Meanwhile, miles away, Sally wants to do
        the same thing.  She doesn't think to run <userinput>svn status
        --show-updates</userinput>, so she has no idea that Harry has
        already locked the file.  She spends hours editing the file,
        and when she tries to commit her change, she discovers that
        either the file is locked or that she's out of date.
        Regardless, her changes aren't mergeable with Harry's.  One of
        these two people has to throw away his or her work, and a lot of
        time has been wasted.</para>
      
      <para>Subversion's solution to this problem is to provide a
        mechanism to remind users that a file ought to be locked
        <emphasis>before</emphasis> the editing begins.  The mechanism
        is a special property:  <literal>svn:needs-lock</literal>.  If
        that property is attached to a file (regardless of its value,
        which is irrelevant), Subversion will try to use
        filesystem-level permissions to make the file read-only&mdash;unless,
        of course, the user has explicitly locked the file.
        When a lock token is present (as a result of using
        <command>svn lock</command>), the file becomes read/write.
        When the lock is released, the file becomes read-only
        again.</para>

      <para>The theory, then, is that if the image file has this
        property attached, Sally would immediately notice
        something is strange when she opens the file for editing:
        many applications alert users immediately when a read-only
        file is opened for editing, and nearly all would
        prevent her from saving changes to the file.  This
        reminds her to lock the file before editing, whereby she
        discovers the preexisting lock:</para>

      <screen>
$ /usr/local/bin/gimp raisin.jpg
gimp: error: file is read-only!
$ ls -l raisin.jpg
-r--r--r--   1 sally   sally   215589 Jun  8 19:23 raisin.jpg
$ svn lock raisin.jpg
svn: Lock request failed: 423 Locked (http://svn.example.com)
$ svn info http://svn.example.com/repos/project/raisin.jpg | grep Lock
Lock Token: opaquelocktoken:fc2b4dee-98f9-0310-abf3-653ff3226e6b
Lock Owner: harry
Lock Created: 2006-06-08 07:29:18 -0500 (Thu, 08 June 2006)
Lock Comment (1 line):
Making some tweaks.  Locking for the next two hours.
$
</screen>

      <tip>
        <para>Users and administrators alike are encouraged to attach
          the <literal>svn:needs-lock</literal> property to any file
          that cannot be contextually merged.  This is the primary
          technique for encouraging good locking habits and preventing
          wasted effort.</para>
      </tip>

      <para>Note that this property is a communication tool that
        works independently from the locking system.  In other words,
        any file can be locked, whether or not this property is
        present.  And conversely, the presence of this property
        doesn't make the repository require a lock when
        committing.</para>

      <para>Unfortunately, the system isn't flawless.  It's possible
        that even when a file has the property, the read-only reminder
        won't always work.  Sometimes applications misbehave and
        <quote>hijack</quote> the read-only file, silently allowing
        users to edit and save the file anyway.  There's not much that
        Subversion can do in this situation&mdash;at the end of the
        day, there's simply no substitution for good interpersonal
        communication.
        <footnote>
          <para>Except, perhaps, a classic Vulcan mind-meld.</para>
        </footnote>
      </para>

    </sect2>

  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.advanced.externals">
    <title>Externals Definitions</title>
    
    <para>Sometimes it is useful to construct a working copy that is
      made out of a number of different checkouts.  For example, you
      may want different subdirectories to come from different
      locations in a repository or perhaps from different
      repositories altogether.  You could certainly set up such a
      scenario by hand&mdash;using <command>svn checkout</command> to
      create the sort of nested working copy structure you are trying
      to achieve.  But if this layout is important for everyone who
      uses your repository, every other user will need to perform the
      same checkout operations that you did.</para>

    <para>Fortunately, Subversion provides support for
      <firstterm>externals definitions</firstterm>.  An externals
      definition is a mapping of a local directory to the
      URL&mdash;and ideally a particular revision&mdash;of a versioned
      directory.  In Subversion, you declare externals definitions in
      groups using the <literal>svn:externals</literal> property.  You
      can create or modify this property using <command>svn
      propset</command> or <command>svn propedit</command> (see <xref
      linkend="svn.advanced.props.manip" />).  It can be set on any
      versioned directory, and its value describes both the external
      repository location and the client-side directory to which that
      location should be checked out.</para>

    <para>The convenience of the <literal>svn:externals</literal>
      property is that once it is set on a versioned directory,
      everyone who checks out a working copy with that directory also
      gets the benefit of the externals definition.  In other words,
      once one person has made the effort to define the nested working
      copy structure, no one else has to bother&mdash;Subversion will,
      after checking out the original working copy, automatically also
      check out the external working copies.</para>

    <warning>
      <para>The relative target subdirectories of externals
        definitions <emphasis>must not</emphasis> already exist on
        your or other users' systems&mdash;Subversion will create them
        when it checks out the external working copy.</para>
    </warning>

    <para>You also get in the externals definition design all the
      regular benefits of Subversion properties.  The definitions are
      versioned.  If you need to change an externals definition, you
      can do so using the regular property modification subcommands.
      When you commit a change to the <literal>svn:externals</literal>
      property, Subversion will synchronize the checked-out items
      against the changed externals definition when you next run
      <userinput>svn update</userinput>.  The same thing will happen when
      others update their working copies and receive your changes to
      the externals definition.</para>

    <tip>
      <para>Because the <literal>svn:externals</literal> property has
        a multiline value, we strongly recommend that you use
        <command>svn propedit</command> instead of <command>svn
        propset</command>.</para>
    </tip>

    <para>Subversion releases prior to 1.5 honor an externals
      definition format that is a multiline table of subdirectories
      (relative to the versioned directory on which the property is
      set), optional revision flags, and fully qualified, absolute
      Subversion repository URLs.  An example of this might looks as
      follows:</para>

    <screen>
$ svn propget svn:externals calc
third-party/sounds             http://svn.example.com/repos/sounds
third-party/skins -r148        http://svn.example.com/skinproj
third-party/skins/toolkit -r21 http://svn.example.com/skin-maker
</screen>

    <para>When someone checks out a working copy of the
      <filename>calc</filename> directory referred to in the previous
      example, Subversion also continues to check out the items found
      in its externals definition.</para>

    <screen>
$ svn checkout http://svn.example.com/repos/calc
A  calc
A  calc/Makefile
A  calc/integer.c
A  calc/button.c
Checked out revision 148.

Fetching external item into calc/third-party/sounds
A  calc/third-party/sounds/ding.ogg
A  calc/third-party/sounds/dong.ogg
A  calc/third-party/sounds/clang.ogg
&hellip;
A  calc/third-party/sounds/bang.ogg
A  calc/third-party/sounds/twang.ogg
Checked out revision 14.

Fetching external item into calc/third-party/skins
&hellip;
</screen>

    <para>As of Subversion 1.5, though, a new format of the
      <literal>svn:externals</literal> property is supported.
      Externals definitions are still multiline, but the order and
      format of the various pieces of information have changed.  The
      new syntax more closely mimics the order of arguments you might
      pass to <command>svn checkout</command>: the optional revision
      flags come first, then the external Subversion repository URL,
      and finally the relative local subdirectory.  Notice, though,
      that this time we didn't say <quote>fully qualified, absolute
      Subversion repository URLs.</quote> That's because the new
      format supports relative URLs and URLs that carry peg revisions.
      The previous example of an externals definition might, in
      Subversion 1.5, look like the following:</para>

    <screen>
$ svn propget svn:externals calc
      http://svn.example.com/repos/sounds third-party/sounds
-r148 http://svn.example.com/skinproj third-party/skins
-r21  http://svn.example.com/skin-maker third-party/skins/toolkit
</screen>

    <para>Or, making use of the peg revision syntax (which we describe
      in detail in <xref linkend="svn.advanced.pegrevs" />), it might
      appear as:</para>

    <screen>
$ svn propget svn:externals calc
http://svn.example.com/repos/sounds third-party/sounds
http://svn.example.com/skinproj@148 third-party/skins
http://svn.example.com/skin-maker@21 third-party/skins/toolkit
</screen>

    <tip>
      <para>You should seriously consider using explicit revision
        numbers in all of your externals definitions.  Doing so means
        that you get to decide when to pull down a different snapshot
        of external information, and exactly which snapshot to pull.
        Besides avoiding the surprise of getting changes to
        third-party repositories that you might not have any control
        over, using explicit revision numbers also means that as you
        backdate your working copy to a previous revision, your
        externals definitions will also revert to the way they looked
        in that previous revision, which in turn means that the
        external working copies will be updated to match the way
        <emphasis>they</emphasis> looked back when your repository was
        at that previous revision.  For software projects, this could
        be the difference between a successful and a failed build of
        an older snapshot of your complex codebase.</para> 
    </tip>

    <para>For most repositories, these three ways of formatting the
      externals definitions have the same ultimate effect.  They all
      bring the same benefits.  Unfortunately, they all bring the same
      annoyances, too.  Since the definitions shown use absolute URLs,
      moving or copying a directory to which they are attached will
      not affect what gets checked out as an external (though the
      relative local target subdirectory will, of course, move with the
      renamed directory).  This can be confusing&mdash;even
      frustrating&mdash;in certain situations.  For example, say you
      have a top-level directory named
      <filename>my-project</filename>, and you've created an externals
      definition on one of its subdirectories
      (<filename>my-project/some-dir</filename>) that tracks the
      latest revision of another of its subdirectories
      (<filename>my-project/external-dir</filename>).</para>

    <screen>
$ svn checkout http://svn.example.com/projects .
A    my-project
A    my-project/some-dir
A    my-project/external-dir
&hellip;
Fetching external item into 'my-project/some-dir/subdir'
Checked out external at revision 11.

Checked out revision 11.
$ svn propget svn:externals my-project/some-dir
subdir http://svn.example.com/projects/my-project/external-dir

$
</screen>

    <para>Now you use <command>svn move</command> to rename the
      <filename>my-project</filename> directory.  At this point, your
      externals definition will still refer to a path under the
      <filename>my-project</filename> directory, even though that
      directory no longer exists.</para>

    <screen>
$ svn move -q my-project renamed-project
$ svn commit -m "Rename my-project to renamed-project."
Deleting       my-project
Adding         renamed-project

Committed revision 12.
$ svn update

Fetching external item into 'renamed-project/some-dir/subdir'
svn: Target path does not exist
$
</screen>

    <para>Also, absolute URLs can cause problems with repositories
      that are available via multiple URL schemes.  For example, if
      your Subversion server is configured to allow everyone to check
      out the repository over <literal>http://</literal> or
      <literal>https://</literal>, but only allow commits to come in
      via <literal>https://</literal>, you have an interesting problem
      on your hands.  If your externals definitions use the
      <literal>http://</literal> form of the repository URLs, you
      won't be able to commit anything from the working copies created
      by those externals.  On the other hand, if they use the
      <literal>https://</literal> form of the URLs, anyone who might
      be checking out via <literal>http://</literal> because his
      client doesn't support <literal>https://</literal> will be
      unable to fetch the external items.  Be aware, too, that if you
      need to reparent your working copy (using <command>svn switch</command>
      with the <option>--relocate</option> option), externals definitions will
      <emphasis>not</emphasis> also be reparented.</para>

   <para>Subversion 1.5 takes a huge step in relieving these
     frustrations.  As mentioned earlier, the URLs used in the new
     externals definition format can be relative, and Subversion
     provides syntax magic for specifying multiple flavors of URL
     relativity.</para>

    <variablelist>
      <varlistentry>
        <term><literal>../</literal></term> 
        <listitem><para>Relative to the URL of the directory on which
          the <literal>svn:externals</literal> property is
          set</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><literal>^/</literal></term> 
        <listitem><para>Relative to the root of the repository in
          which the <literal>svn:externals</literal> property is
          versioned</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><literal>//</literal></term> 
        <listitem><para>Relative to the scheme of the URL of the
          directory on which the <literal>svn:externals</literal>
          property is set</para></listitem>
      </varlistentry>
      <varlistentry>
        <term><literal>/</literal></term>
        <listitem><para>Relative to the root URL of the server on
          which the <literal>svn:externals</literal> property is
          versioned</para></listitem>
      </varlistentry>
    </variablelist>

    <para>So, looking a fourth time at our previous externals
      definition example, and making use of the new absolute URL
      syntax in various ways, we might now see:</para>

    <screen>
$ svn propget svn:externals calc
^/sounds third-party/sounds
/skinproj@148 third-party/skins
//svn.example.com/skin-maker@21 third-party/skins/toolkit
</screen>

    <para>The support that exists for externals definitions in
      Subversion remains less than ideal, though.  An externals
      definition can point only to directories, not to files.  Also, the
      local subdirectory part of the definition cannot contain
      <literal>..</literal> parent directory indicators (such as
      <filename>../../skins/myskin</filename>).  Perhaps most
      disappointingly, the working copies created via the externals
      definition support are still disconnected from the primary
      working copy (on whose versioned directories the
      <literal>svn:externals</literal> property was actually set).
      And Subversion still truly operates only on nondisjoint working
      copies.  So, for example, if you want to commit changes that
      you've made in one or more of those external working copies, you
      must run <command>svn commit</command> explicitly on those
      working copies&mdash;committing on the primary working copy will
      not recurse into any external ones.</para>

    <para>We've already mentioned some of the additional shortcomings
      of the old <literal>svn:externals</literal> format and how the
      new Subversion 1.5 format improves upon it.  But be careful when
      making use of the new format that you don't inadvertently cause
      problems for other folks accessing your repository who are using
      older Subversion clients.  While Subversion 1.5 clients will
      continue to recognize and support the original externals
      definition format, older clients will <emphasis>not</emphasis>
      be able to correctly parse the new format.</para>

    <para>Besides the <command>svn checkout</command>, <command>svn
      update</command>, <command>svn switch</command>, and
      <command>svn export</command> commands which actually manage the
      <firstterm>disjoint</firstterm> (or disconnected) subdirectories
      into which externals are checked out, the <command>svn
      status</command> command also recognizes externals definitions.
      It displays a status code of <literal>X</literal> for the
      disjoint external subdirectories, and then recurses into those
      subdirectories to display the status of the external items
      themselves.  You can pass the
      <option>--ignore-externals</option> option to any of these
      subcommands to disable externals definition processing.</para>

  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.advanced.pegrevs">
    <title>Peg and Operative Revisions</title>

    <para>We copy, move, rename, and completely replace files and
      directories on our computers all the time.  And your version
      control system shouldn't get in the way of your doing these
      things with your version-controlled files and directories,
      either.  Subversion's file management support is quite
      liberating, affording almost as much flexibility for versioned
      files as you'd expect when manipulating your unversioned ones.
      But that flexibility means that across the lifetime of your
      repository, a given versioned object might have many paths, and
      a given path might represent several entirely different
      versioned objects.  This introduces a certain level of
      complexity to your interactions with those paths and
      objects.</para>

    <para>Subversion is pretty smart about noticing when an object's
      version history includes such <quote>changes of address.</quote>
      For example, if you ask for the revision history log of a
      particular file that was renamed last week, Subversion happily
      provides all those logs&mdash;the revision in which the rename
      itself happened, plus the logs of relevant revisions both before
      and after that rename.  So, most of the time, you don't even
      have to think about such things.  But occasionally, Subversion
      needs your help to clear up ambiguities.</para>

    <para>The simplest example of this occurs when a directory or file
      is deleted from version control, and then a new directory or
      file is created with the same name and added to version control.
      The thing you deleted and the thing you later added aren't the
      same thing.  They merely happen to have had the same
      path&mdash;<filename>/trunk/object</filename>, for example.
      What, then, does it mean to ask Subversion about the history of
      <filename>/trunk/object</filename>?  Are you asking about the
      thing currently at that location, or the old thing you deleted
      from that location?  Are you asking about the operations that
      have happened to <emphasis>all</emphasis> the objects that have
      ever lived at that path?  Subversion needs a hint about what you
      really want.</para>

    <para>And thanks to moves, versioned object history can get far
      more twisted than even that.  For example, you might have a
      directory named <filename>concept</filename>, containing some
      nascent software project you've been toying with.  Eventually,
      though, that project matures to the point that the idea seems to
      actually have some wings, so you do the unthinkable and decide
      to give the project a name.
      <footnote>
        <para><quote>You're not supposed to name it.  Once you name it,
          you start getting attached to it.</quote>&mdash;Mike
          Wazowski</para>
      </footnote>
      Let's say you called your software Frabnaggilywort.  At this
      point, it makes sense to rename the directory to reflect the
      project's new name, so <filename>concept</filename> is renamed
      to <filename>frabnaggilywort</filename>.  Life goes on,
      Frabnaggilywort releases a 1.0 version and is downloaded and
      used daily by hordes of people aiming to improve their
      lives.</para>
    
    <para>It's a nice story, really, but it doesn't end there.
      Entrepreneur that you are, you've already got another think in
      the tank.  So you make a new directory,
      <filename>concept</filename>, and the cycle begins again.  In
      fact, the cycle begins again many times over the years, each
      time starting with that old <filename>concept</filename>
      directory, then sometimes seeing that directory renamed as the
      idea cures, sometimes seeing it deleted when you scrap the idea.
      Or, to get really sick, maybe you rename
      <filename>concept</filename> to something else for a while, but
      later rename the thing back to <filename>concept</filename> for
      some reason.</para>

    <para>In scenarios like these, attempting to instruct
      Subversion to work with these reused paths can be a little like
      instructing a motorist in Chicago's West Suburbs to drive east
      down Roosevelt Road and turn left onto Main Street.  In a mere
      20 minutes, you can cross <quote>Main Street</quote> in
      Wheaton, Glen Ellyn, and Lombard.  And no, they aren't the same
      street.  Our motorist&mdash;and our Subversion&mdash;need a
      little more detail to do the right thing.</para>

    <para>In version 1.1, Subversion introduced a way for you to tell
      it exactly which Main Street you meant.  It's called the
      <firstterm>peg revision</firstterm>, and it is provided to
      Subversion for the sole purpose of identifying a unique line of
      history.  Because at most, one versioned object may occupy a path
      at any given time&mdash;or, more precisely, in any one
      revision&mdash;the combination of a path and a peg revision is
      all that is needed to refer to a specific line of history.  Peg
      revisions are specified to the Subversion command-line client
      using <firstterm>at syntax</firstterm>, so called because the
      syntax involves appending an <quote>at sign</quote>
      (<literal>@</literal>) and the peg revision to the end of the
      path with which the revision is associated.</para>

    <para>But what of the <option>--revision</option>
      (<option>-r</option>) of which we've spoken so much in this
      book?  That revision (or set of revisions) is called the
      <firstterm>operative revision</firstterm> (or
      <firstterm>operative revision range</firstterm>).  Once a
      particular line of history has been identified using a path and
      peg revision, Subversion performs the requested operation using
      the operative revision(s).  To map this to our Chicagoland
      streets analogy, if we are told to go to 606 N. Main Street in
      Wheaton,
      <footnote>
        <para>606 N. Main Street, Wheaton, Illinois, is the home of
          the Wheaton <emphasis>History</emphasis> Center.  It seemed
          appropriate&hellip;.</para>
      </footnote>
      we can think of <quote>Main Street</quote> as our path and
      <quote>Wheaton</quote> as our peg revision.  These two pieces of
      information identify a unique path that can be traveled (north or
      south on Main Street), and they keep us from traveling up and
      down the wrong Main Street in search of our destination.  Now we
      throw in <quote>606 N.</quote> as our operative revision of
      sorts, and we know <emphasis>exactly</emphasis> where to
      go.</para>

    <sidebar>
      <title>The Peg Revision Algorithm</title>
      
      <para>The Subversion command-line client performs the peg revision
        algorithm any time it needs to resolve possible ambiguities in
        the paths and revisions provided to it.  Here's an example of
        such an invocation:</para>

      <screen>
$ svn <replaceable>command</replaceable> -r <replaceable>OPERATIVE-REV</replaceable> item@<replaceable>PEG-REV</replaceable>
</screen>
      
      <para>If <replaceable>OPERATIVE-REV</replaceable> is older than
        <replaceable>PEG-REV</replaceable>, the algorithm is as
        follows:</para>

      <orderedlist>
        <listitem>
          <para>Locate <replaceable>item</replaceable> in the revision
            identified by <replaceable>PEG-REV</replaceable>.  There
            can be only one such object.</para>
        </listitem>
        <listitem>
          <para>Trace the object's history backwards (through any
            possible renames) to its ancestor in the revision
            <replaceable>OPERATIVE-REV</replaceable>.</para>
        </listitem>
        <listitem>
          <para>Perform the requested action on that ancestor,
            wherever it is located, or whatever its name might
            be or might have been at that time.</para>
        </listitem>
      </orderedlist>

      <para>But what if <replaceable>OPERATIVE-REV</replaceable> is
        <emphasis>younger</emphasis> than
        <replaceable>PEG-REV</replaceable>?  Well, that adds some
        complexity to the theoretical problem of locating the path in
        <replaceable>OPERATIVE-REV</replaceable>, because the path's
        history could have forked multiple times (thanks to copy
        operations) between <replaceable>PEG-REV</replaceable> and
        <replaceable>OPERATIVE-REV</replaceable>.  And that's not
        all&mdash;Subversion doesn't store enough information to
        performantly trace an object's history forward, anyway.  So
        the algorithm is a little different:</para>

      <orderedlist>
        <listitem>
          <para>Locate <replaceable>item</replaceable> in the revision
            identified by <replaceable>OPERATIVE-REV</replaceable>.  There
            can be only one such object.</para>
        </listitem>
        <listitem>
          <para>Trace the object's history backward (through any
            possible renames) to its ancestor in the revision
            <replaceable>PEG-REV</replaceable>.</para>
        </listitem>
        <listitem>
          <para>Verify that the object's location (path-wise) in
            <replaceable>PEG-REV</replaceable> is the same as it is in
            <replaceable>OPERATIVE-REV</replaceable>.  If that's the
            case, at least the two locations are known to be
            directly related, so perform the requested action on the
            location in <replaceable>OPERATIVE-REV</replaceable>.
            Otherwise, relatedness was not established, so error out
            with a loud complaint that no viable location was found.
            (Someday, we expect that Subversion will be able to handle
            this usage scenario with more flexibility and
            grace.)</para>
        </listitem>
      </orderedlist>

      <para>Note that even when you don't explicitly supply a peg
        revision or operative revision, they are still present.  For
        your convenience, the default peg revision is
        <literal>BASE</literal> for working copy items and
        <literal>HEAD</literal> for repository URLs.  And when no
        operative revision is provided, it defaults to being the same
        revision as the peg revision.</para>
        
    </sidebar>

    <para>Say that long ago we created our repository, and in revision 1
      we added our first <filename>concept</filename> directory, plus an
      <filename>IDEA</filename> file in that directory talking about
      the concept.  After several revisions in which real code was
      added and tweaked, we, in revision 20, renamed this directory to
      <filename>frabnaggilywort</filename>.  By revision 27, we had a
      new concept, a new <filename>concept</filename> directory to
      hold it, and a new <filename>IDEA</filename> file to describe
      it.  And then five years and thousands of revisions flew by,
      just like they would in any good romance story.</para>

    <para>Now, years later, we wonder what the
      <filename>IDEA</filename> file looked like back in revision 1.
      But Subversion needs to know whether we are asking about how the
      <emphasis>current</emphasis> file looked back in revision 1, or
      whether we are asking for the contents of whatever file lived at
      <filename>concepts/IDEA</filename> in revision 1.  Certainly
      those questions have different answers, and because of peg
      revisions, you can ask those questions.  To find out how the
      current <filename>IDEA</filename> file looked in that old
      revision, you run:</para>

    <screen>
$ svn cat -r 1 concept/IDEA 
svn: Unable to find repository location for 'concept/IDEA' in revision 1
</screen>

    <para>Of course, in this example, the current
      <filename>IDEA</filename> file didn't exist yet in revision 1,
      so Subversion gives an error.  The previous command is shorthand
      for a longer notation which explicitly lists a peg revision.
      The expanded notation is:</para>

    <screen>
$ svn cat -r 1 concept/IDEA@BASE
svn: Unable to find repository location for 'concept/IDEA' in revision 1
</screen>

    <para>And when executed, it has the expected results.</para>

    <para>The perceptive reader is probably wondering at this point whether
      the peg revision syntax causes problems for working copy paths
      or URLs that actually have at signs in them.  After
      all, how does <command>svn</command> know whether
      <literal>news@11</literal> is the name of a directory in my
      tree or just a syntax for <quote>revision 11 of
      <filename>news</filename></quote>?  Thankfully, while
      <command>svn</command> will always assume the latter, there is a
      trivial workaround.  You need only append an at sign to the
      end of the path, such as <literal>news@11@</literal>.
      <command>svn</command> cares only about the last at sign in
      the argument, and it is not considered illegal to omit a literal
      peg revision specifier after that at sign.  This workaround
      even applies to paths that end in an at sign&mdash;you would
      use <literal>filename@@</literal> to talk about a file named
      <filename>filename@</filename>.</para>

    <para>Let's ask the other question, then&mdash;in revision 1, what
      were the contents of whatever file occupied the address
      <filename>concepts/IDEA</filename> at the time?  We'll use an
      explicit peg revision to help us out.</para>

    <screen>
$ svn cat concept/IDEA@1
The idea behind this project is to come up with a piece of software
that can frab a naggily wort.  Frabbing naggily worts is tricky
business, and doing it incorrectly can have serious ramifications, so
we need to employ over-the-top input validation and data verification
mechanisms.
</screen>

    <para>Notice that we didn't provide an operative revision this
      time.  That's because when no operative revision is specified,
      Subversion assumes a default operative revision that's the same
      as the peg revision.</para>

    <para>As you can see, the output from our operation appears to be
      correct.  The text even mentions frabbing naggily worts, so this
      is almost certainly the file that describes the software now
      called Frabnaggilywort.  In fact, we can verify this using the
      combination of an explicit peg revision and explicit operative
      revision.  We know that in <literal>HEAD</literal>, the
      Frabnaggilywort project is located in the
      <filename>frabnaggilywort</filename> directory.  So we specify
      that we want to see how the line of history identified in
      <literal>HEAD</literal> as the path
      <filename>frabnaggilywort/IDEA</filename> looked in revision
      1.</para>

    <screen>
$ svn cat -r 1 frabnaggilywort/IDEA@HEAD
The idea behind this project is to come up with a piece of software
that can frab a naggily wort.  Frabbing naggily worts is tricky
business, and doing it incorrectly can have serious ramifications, so
we need to employ over-the-top input validation and data verification
mechanisms.
</screen>

    <para>And the peg and operative revisions need not be so trivial,
      either.  For example, say <filename>frabnaggilywort</filename>
      had been deleted from <literal>HEAD</literal>, but we know it
      existed in revision 20, and we want to see the diffs for its
      <filename>IDEA</filename> file between revisions 4 and 10.  We
      can use the peg revision 20 in conjunction with the URL that
      would have held Frabnaggilywort's <filename>IDEA</filename> file
      in revision 20, and then use 4 and 10 as our operative revision
      range.</para>

    <screen>
$ svn diff -r 4:10 http://svn.red-bean.com/projects/frabnaggilywort/IDEA@20
Index: frabnaggilywort/IDEA
===================================================================
--- frabnaggilywort/IDEA	(revision 4)
+++ frabnaggilywort/IDEA	(revision 10)
@@ -1,5 +1,5 @@
-The idea behind this project is to come up with a piece of software
-that can frab a naggily wort.  Frabbing naggily worts is tricky
-business, and doing it incorrectly can have serious ramifications, so
-we need to employ over-the-top input validation and data verification
-mechanisms.
+The idea behind this project is to come up with a piece of
+client-server software that can remotely frab a naggily wort.
+Frabbing naggily worts is tricky business, and doing it incorrectly
+can have serious ramifications, so we need to employ over-the-top
+input validation and data verification mechanisms.
</screen>

    <para>Fortunately, most folks aren't faced with such complex
      situations.  But when you are, remember that peg revisions are
      that extra hint Subversion needs to clear up ambiguity.</para>

  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.advanced.changelists">
    <title>Changelists</title>

    <para>It is commonplace for a developer to find himself working at
      any given time on multiple different, distinct changes to a
      particular bit of source code.  This isn't necessarily due to
      poor planning or some form of digital masochism.  A software
      engineer often spots bugs in his peripheral vision while working
      on some nearby chunk of source code.  Or perhaps he's halfway
      through some large change when he realizes the solution he's
      working on is best committed as several smaller logical units.
      Often, these logical units aren't nicely contained in some
      module, safely separated from other changes.  The units might
      overlap, modifying different files in the same module, or even
      modifying different lines in the same file.</para>

    <para>Developers can employ various work methodologies
      to keep these logical changes organized.  Some use
      separate working copies of the same repository to hold each
      individual change in progress.  Others might choose to create
      short-lived feature branches in the repository and use a single
      working copy that is constantly switched to point to one such
      branch or another.  Still others use <command>diff</command> and
      <command>patch</command> tools to back up and restore uncommitted
      changes to and from patch files associated with each change.
      Each of these methods has its pros and cons, and to a large
      degree, the details of the changes being made heavily influence
      the methodology used to distinguish them.</para>

    <para>Subversion 1.5 brings a new
      <firstterm>changelists</firstterm> feature that adds yet
      another method to the mix.  Changelists are basically arbitrary
      labels (currently at most one per file) applied to working copy files for the express purpose of
      associating multiple files together.  Users of many of Google's
      software offerings are familiar with this concept already.  For
      example, <ulink url="http://mail.google.com/">Gmail</ulink>
      doesn't provide the traditional folders-based email organization
      mechanism.  In Gmail, you apply arbitrary labels to emails, and
      multiple emails can be said to be part of the same group if they
      happen to share a particular label.  Viewing only a group of
      similarly labeled emails then becomes a simple user interface
      trick.  Many other Web 2.0 sites have similar
      mechanisms&mdash;consider the <quote>tags</quote> used by sites
      such as <ulink url="http://www.youtube.com/">YouTube</ulink> and
      <ulink url="http://www.flickr.com/">Flickr</ulink>,
      <quote>categories</quote> applied to blog posts, and so on.
      Folks understand today that organization of data is critical,
      but that how that data is organized needs to be a flexible
      concept.  The old files-and-folders paradigm is too rigid for
      some applications.</para>

    <para>Subversion's changelist support allows you to create
      changelists by applying labels to files you want to be
      associated with that changelist, remove those labels, and limit
      the scope of the files on which its subcommands operate to only
      those bearing a particular label.  In this section, we'll look
      in detail at how to do these things.</para>

    <!-- =============================================================== -->
    <sect2 id="svn.advanced.changelists.creating">
      <title>Creating and Modifying Changelists</title>

      <para>You can create, modify, and delete changelists using the
        <command>svn changelist</command> command.  More accurately,
        you use this command to set or unset the changelist
        association of a particular working copy file.  A changelist
        is effectively created the first time you label a file with
        that changelist; it is deleted when you remove that label from
        the last file that had it.  Let's examine a usage scenario
        that demonstrates these concepts.</para>

      <para>Harry is fixing some bugs in the calculator application's
        mathematics logic.  His work leads him to change a couple of
        files:</para>

      <screen>
$ svn status
M      integer.c
M      mathops.c
$
</screen>

      <para>While testing his bug fix, Harry notices that his changes
        bring to light a tangentially related bug in the user
        interface logic found in <filename>button.c</filename>.  Harry
        decides that he'll go ahead and fix that bug, too, as a
        separate commit from his math fixes.  Now, in a small working
        copy with only a handful of files and few logical changes,
        Harry can probably keep his two logical change groupings
        mentally organized without any problem.  But today he's going
        to use Subversion's changelists feature as a special favor to
        the authors of this book.</para>

      <para>Harry first creates a changelist and associates with it
        the two files he's already changed.  He does this by using the
        <command>svn changelist</command> command to assign the same
        arbitrary changelist name to those files:</para>

      <screen>
$ svn changelist math-fixes integer.c mathops.c
Path 'integer.c' is now a member of changelist 'math-fixes'.
Path 'mathops.c' is now a member of changelist 'math-fixes'.
$ svn status

--- Changelist 'math-fixes':
M      integer.c
M      mathops.c
$
</screen>

      <para>As you can see, the output of <command>svn
        status</command> reflects this new grouping.</para>

      <para>Harry now sets off to fix the secondary UI problem.  Since
        he knows which file he'll be changing, he assigns that path to
        a changelist, too.  Unfortunately, Harry carelessly assigns this
        third file to the same changelist as the previous two files:</para>

      <screen>
$ svn changelist math-fixes button.c
Path 'button.c' is now a member of changelist 'math-fixes'.
$ svn status

--- Changelist 'math-fixes':
       button.c
M      integer.c
M      mathops.c
$
</screen>

      <para>Fortunately, Harry catches his mistake.  At this point, he
        has two options.  He can remove the changelist association
        from <filename>button.c</filename>, and then assign a
        different changelist name:</para>

      <screen>
$ svn changelist --remove button.c
Path 'button.c' is no longer a member of a changelist.
$ svn changelist ui-fix button.c
Path 'button.c' is now a member of changelist 'ui-fix'.
$
</screen>

      <para>Or, he can skip the removal and just assign a new
        changelist name.  In this case, Subversion will first warn
        Harry that <filename>button.c</filename> is being removed from
        the first changelist:</para>

      <screen>
$ svn changelist ui-fix button.c
svn: warning: Removing 'button.c' from changelist 'math-fixes'.
Path 'button.c' is now a member of changelist 'ui-fix'.
$ svn status

--- Changelist 'ui-fix':
       button.c

--- Changelist 'math-fixes':
M      integer.c
M      mathops.c
$
</screen>

      <para>Harry now has two distinct changelists present in his
        working copy, and <command>svn status</command> will group its
        output according to these changelist determinations.  Notice
        that even though Harry hasn't yet modified
        <filename>button.c</filename>, it still shows up in the output
        of <command>svn status</command> as interesting because it has
        a changelist assignment.  Changelists can be added to and
        removed from files at any time, regardless of whether they
        contain local modifications.</para>

      <para>Harry now fixes the user interface problem in
        <filename>button.c</filename>.</para>

      <screen>
$ svn status

--- Changelist 'ui-fix':
M      button.c

--- Changelist 'math-fixes':
M      integer.c
M      mathops.c
$
</screen>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.advanced.changelists.asfilters">
      <title>Changelists As Operation Filters</title>

      <para>The visual grouping that Harry sees in the output of
        <command>svn status</command> as shown in our previous section
        is nice, but not entirely useful.  The
        <command>status</command> command is but one of many
        operations that he might wish to perform on his working copy.
        Fortunately, many of Subversion's other operations understand
        how to operate on changelists via the use of the
        <option>--changelist</option> option.</para>

      <para>When provided with a <option>--changelist</option> option,
        Subversion commands will limit the scope of their operation to
        only those files to which a particular changelist name is
        assigned.  If Harry now wants to see the actual changes he's
        made to the files in his <literal>math-fixes</literal>
        changelist, he <emphasis>could</emphasis> explicitly list only
        the files that make up that changelist on the <command>svn
        diff</command> command line.</para>

      <screen>
$ svn diff integer.c mathops.c
Index: integer.c
===================================================================
--- integer.c	(revision 1157)
+++ integer.c	(working copy)
&hellip;
Index: mathops.c
===================================================================
--- mathops.c	(revision 1157)
+++ mathops.c	(working copy)
&hellip;
$
</screen>

      <para>That works okay for a few files, but what if Harry's
        change touched 20 or 30 files?  That would be an annoyingly
        long list of explicitly named files.  Now that he's using
        changelists, though, Harry can avoid explicitly listing the
        set of files in his changelist from now on, and instead
        provide just the changelist name:</para>

      <screen>
$ svn diff --changelist math-fixes
Index: integer.c
===================================================================
--- integer.c	(revision 1157)
+++ integer.c	(working copy)
&hellip;
Index: mathops.c
===================================================================
--- mathops.c	(revision 1157)
+++ mathops.c	(working copy)
&hellip;
$
</screen>

      <para>And when it's time to commit, Harry can again use the
        <option>--changelist</option> option to limit the scope of the
        commit to files in a certain changelist.  He might commit his
        user interface fix by doing the following:</para>

      <screen>
$ svn ci -m "Fix a UI bug found while working on math logic." \
      --changelist ui-fix
Sending        button.c
Transmitting file data .
Committed revision 1158.
$
</screen>

      <para>In fact, the <command>svn commit</command> command
        provides a second changelists-related option:
        <option>--keep-changelists</option>.  Normally, changelist
        assignments are removed from files after they are committed.
        But if <option>--keep-changelists</option> is provided,
        Subversion will leave the changelist assignment on the
        committed (and now unmodified) files.  In any case, committing
        files assigned to one changelist leaves other changelists
        undisturbed.</para>

      <screen>
$ svn status

--- Changelist 'math-fixes':
M      integer.c
M      mathops.c
$
</screen>

      <note>
        <para>The <option>--changelist</option> option acts only as a
          filter for Subversion command targets, and will not add
          targets to an operation.  For example, on a commit operation
          specified as <userinput>svn commit /path/to/dir</userinput>, the
          target is the directory <filename>/path/to/dir</filename>
          and its children (to infinite depth).  If you then add a
          changelist specifier to that command, only those files in
          and under <filename>/path/to/dir</filename> that are
          assigned that changelist name will be considered as targets
          of the commit&mdash;the commit will not include files
          located elsewhere (such is in
          <filename>/path/to/another-dir</filename>), regardless of
          their changelist assignment, even if they are part of the
          same working copy as the operation's target(s).</para>
      </note>

      <para>Even the <command>svn changelist</command> command accepts
        the <option>--changelist</option> option.  This allows you to
        quickly and easily rename or remove a changelist:</para>

      <screen>
$ svn changelist math-bugs --changelist math-fixes --depth infinity .
svn: warning: Removing 'integer.c' from changelist 'math-fixes'.
Path 'integer.c' is now a member of changelist 'math-bugs'.
svn: warning: Removing 'mathops.c' from changelist 'math-fixes'.
Path 'mathops.c' is now a member of changelist 'math-bugs'.
$ svn changelist --remove --changelist math-bugs --depth infinity .
Path 'integer.c' is no longer a member of a changelist.
Path 'mathops.c' is no longer a member of a changelist.
$
</screen>

      <para>Finally, you can specify multiple instances of the
        <option>--changelist</option> option on a single command
        line.  Doing so limits the operation you are performing to
        files found in any of the specified changesets.</para>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.advanced.changelists.limitations">
      <title>Changelist Limitations</title>

      <para>Subversion's changelist feature is a handy tool for
        grouping working copy files, but it does have a few limitations.
        Changelists are artifacts of a particular working copy, which
        means that changelist assignments cannot be propagated to the
        repository or otherwise shared with other users.  Changelists
        can be assigned only to files&mdash;Subversion doesn't
        currently support the use of changelists with directories.
        Finally, you can have at most one changelist assignment on a
        given working copy file.  Here is where the blog post category
        and photo service tag analogies break down&mdash;if you find
        yourself needing to assign a file to multiple changelists,
        you're out of luck.</para>

    </sect2>
  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.serverconfig.netmodel">
    <title>Network Model</title>

    <para>At some point, you're going to need to understand how your
      Subversion client communicates with its server.  Subversion's
      networking layer is abstracted, meaning that Subversion clients
      exhibit the same general behaviors no matter what sort of server
      they are operating against.  Whether speaking the HTTP protocol
      (<literal>http://</literal>) with the Apache HTTP Server or
      speaking the custom Subversion protocol
      (<literal>svn://</literal>) with <command>svnserve</command>,
      the basic network model is the same.  In this section, we'll
      explain the basics of that network model, including how
      Subversion manages authentication and authorization
      matters.</para>

    <!-- =============================================================== -->
    <sect2 id="svn.serverconfig.netmodel.reqresp">
      <title>Requests and Responses</title>

      <para>The Subversion client spends most of its time managing
        working copies.  When it needs information from a remote
        repository, however, it makes a network request, and the
        server responds with an appropriate answer.  The details of
        the network protocol are hidden from the user&mdash;the client
        attempts to access a URL, and depending on the URL scheme, a
        particular protocol is used to contact the server (see the sidebar <xref
        linkend="svn.basic.in-action.wc.sb-1"/>).</para>

      <tip><para>Run <userinput>svn --version</userinput> to see
        which URL schemes and protocols the client knows how to
        use.</para>
      </tip>

      <para>When the server process receives a client request, it
        often demands that the client identify itself.  It issues
        an authentication challenge to the client, and the client
        responds by providing <firstterm>credentials</firstterm> back
        to the server.  Once authentication is complete, the server
        responds with the original information that the client asked for.
        Notice that this system is different from systems such as CVS,
        where the client preemptively offers credentials (<quote>logs
        in</quote>) to the server before ever making a request.  In
        Subversion, the server <quote>pulls</quote> credentials by
        challenging the client at the appropriate moment, rather than
        the client <quote>pushing</quote> them.  This makes certain
        operations more elegant.  For example, if a server is
        configured to allow anyone in the world to read a repository,
        the server will never issue an authentication challenge
        when a client attempts to <command>svn checkout</command>.</para>

      <para>If the particular network requests issued by the client
        result in a new revision being created in the repository
        (e.g., <command>svn commit</command>), Subversion uses the
        authenticated username associated with those requests as the
        author of the revision.  That is, the authenticated user's
        name is stored as the value of the
        <literal>svn:author</literal> property on the new revision
        (see <xref linkend="svn.ref.properties"/>).  If
        the client was not authenticated (i.e., if the server
        never issued an authentication challenge), the revision's
        <literal>svn:author</literal> property is empty.
      </para>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.serverconfig.netmodel.credcache">
      <title>Client Credentials Caching</title>

      <para>Many servers are configured to require authentication on
        every request.  This would be a big annoyance to users if
        they were forced to type their passwords over and over again.
        Fortunately, the Subversion client has a remedy for
        this&mdash;a built-in system for caching authentication
        credentials on disk.  By default, whenever the command-line
        client successfully responds to a server's authentication
        challenge, it saves the credentials in the user's private
        runtime configuration area
        (<filename>~/.subversion/auth/</filename> on Unix-like systems
        or <filename>%APPDATA%/Subversion/auth/</filename> on Windows;
        see <xref linkend="svn.advanced.confarea" /> for more details
        about the runtime configuration system).  Successful
        credentials are cached on disk and keyed on a combination of the
        server's hostname, port, and authentication realm.</para>

      <para>When the client receives an authentication challenge, it
        first looks for the appropriate credentials in the user's disk
        cache.  If seemingly suitable credentials are not present, or
        if the cached credentials ultimately fail to authenticate,
        the client will, by default, fall back to prompting the
        user for the necessary information.</para>

      <para>The security-conscious reader will suspect immediately
        that there is reason for concern here.  <quote>Caching
        passwords on disk?  That's terrible!  You should never do
        that!</quote></para>

      <para>The Subversion developers recognize the legitimacy of such
        concerns, and so Subversion works with available mechanisms
        provided by the operating system and environment to try to
        minimize the risk of leaking this information.  Here's a
        breakdown of what this means for users on the most common
        platforms:</para>

      <itemizedlist>

        <listitem>
          <para>On Windows 2000 and later, the Subversion client uses
            standard Windows cryptography services to encrypt the
            password on disk.  Because the encryption key is managed
            by Windows and is tied to the user's own login
            credentials, only the user can decrypt the cached
            password.  (Note that if the user's Windows account password
            is reset by an administrator, all of the cached passwords
            become undecipherable.  The Subversion client will behave
            as though they don't exist, prompting for passwords when
            required.)</para>
        </listitem>

        <listitem>
          <para>Similarly, on Mac OS X, the Subversion client stores
            all repository passwords in the login keyring (managed by
            the Keychain service), which is protected by the user's
            account password.  User preference settings can impose
            additional policies, such as requiring that the user's account
            password be entered each time the Subversion password is
            used.</para>
        </listitem>

        <listitem>
          <para>For other Unix-like operating systems, no standard
            <quote>keychain</quote> services exist.  However,
            the <filename>auth/</filename> caching area is still
            permission-protected so that only the user (owner) can
            read data from it, not the world at large.  The operating
            system's own file permissions protect the passwords.</para>
        </listitem>

      </itemizedlist>

      <para>Of course, for the truly paranoid, none of these
        mechanisms meets the test of perfection.  So for those folks
        willing to sacrifice convenience for the ultimate in security,
        Subversion provides various ways of disabling its credentials
        caching system altogether.</para>

      <para>To disable caching for a single command, pass the
        <option>--no-auth-cache</option> option:</para>

      <screen>
$ svn commit -F log_msg.txt --no-auth-cache
Authentication realm: &lt;svn://host.example.com:3690&gt; example realm
Username:  joe
Password for 'joe':

Adding         newfile
Transmitting file data .
Committed revision 2324.

# password was not cached, so a second commit still prompts us

$ svn delete newfile
$ svn commit -F new_msg.txt
Authentication realm: &lt;svn://host.example.com:3690&gt; example realm
Username:  joe
&hellip;
</screen>

      <para>Or, if you want to disable credential caching permanently,
        you can edit the <filename>config</filename> file in your
        runtime configuration area and set the
        <option>store-auth-creds</option> option to
        <literal>no</literal>.  This will prevent the storing of
        credentials used in any Subversion interactions you perform on
        the affected computer.  This can be extended to cover all
        users on the computer, too, by modifying the system-wide
        runtime configuration area (described in <xref
        linkend="svn.advanced.confarea.layout" />).</para>

      <screen>
[auth]
store-auth-creds = no
</screen>

      <para>Sometimes users will want to remove specific credentials
        from the disk cache.  To do this, you need to navigate into
        the <filename>auth/</filename> area and manually delete the
        appropriate cache file.  Credentials are cached in individual
        files;  if you look inside each file, you will see keys and
        values.  The <literal>svn:realmstring</literal> key describes
        the particular server realm that the file is associated
        with:</para>

      <screen>
$ ls ~/.subversion/auth/svn.simple/
5671adf2865e267db74f09ba6f872c28
3893ed123b39500bca8a0b382839198e
5c3c22968347b390f349ff340196ed39

$ cat ~/.subversion/auth/svn.simple/5671adf2865e267db74f09ba6f872c28

K 8
username
V 3
joe
K 8
password
V 4
blah
K 15
svn:realmstring
V 45
&lt;https://svn.domain.com:443&gt; Joe's repository
END
</screen>

      <para>Once you have located the proper cache file, just delete
        it.</para>

      <para>One last word about <command>svn</command>'s
        authentication behavior, specifically regarding the
        <option>--username</option> and <option>--password</option>
        options.  Many client subcommands accept these options, but it
        is important to understand that using these options does
        <emphasis>not</emphasis> automatically send credentials to the
        server.  As discussed earlier, the server <quote>pulls</quote>
        credentials from the client when it deems necessary; the
        client cannot <quote>push</quote> them at will.  If a username
        and/or password are passed as options, they will be
        presented to the server only if the server requests them.  These
        options are typically used to authenticate as a different user
        than Subversion would have chosen by default (such as your
        system login name) or when trying to avoid interactive
        prompting (such as when calling <command>svn</command> from a
        script).</para>

      <note>
        <para>A common mistake is to misconfigure a server so
          that it never issues an authentication challenge.  When
          users pass <option>--username</option> and
          <option>--password</option> options to the client, they're
          surprised to see that they're never used; that is, new
          revisions still appear to have been committed
          anonymously!</para>
      </note>

      <para>Here is a final summary that describes how a Subversion
        client behaves when it receives an authentication
        challenge.</para>

      <orderedlist>
        <listitem>
          <para>First, the client checks whether the user specified
            any credentials as command-line options
            (<option>--username</option> and/or
            <option>--password</option>).  If so, the client will try
            to use those credentials to authenticate against the
            server.</para>
        </listitem>
        <listitem>
          <para>If no command-line credentials were provided, or the
            provided ones were invalid, the client looks up the server's
            hostname, port, and realm in the runtime configuration's
            <filename>auth/</filename> area, to see whether appropriate 
            credentials are cached there.  If so, it attempts to use
            those credentials to authenticate.</para>
        </listitem>
        <listitem>
          <para>Finally, if the previous mechanisms failed to
            successfully authenticate the user against the server, the
            client resorts to interactively prompting the user for
            valid credentials (unless instructed not to do so via the
            <option>--non-interactive</option> option or its
            client-specific equivalents).</para>
        </listitem>
      </orderedlist>

      <para>If the client successfully authenticates by any of these
        methods, it will attempt to cache the credentials on disk
        (unless the user has disabled this behavior, as mentioned
        earlier).</para>

    </sect2>

  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.advanced.summary">
    <title>Summary</title>

    <para>After reading this chapter, you should have a firm grasp on
      some of Subversion's features that, while perhaps not used
      <emphasis>every</emphasis> time you interact with your version
      control system, are certainly handy to know about.  But don't
      stop here!  Read on to the following chapter, where you'll learn
      about branches, tags, and merging.  Then you'll have nearly full
      mastery of the Subversion client.  Though our lawyers won't
      allow us to promise you anything, this additional knowledge
      could make you measurably more cool.
      <footnote>
        <para>No purchase necessary.  Certains terms and conditions
          apply.  No guarantee of coolness&mdash;implicit or 
          otherwise&mdash;exists.  Mileage may vary.</para>
      </footnote>
    </para>

  </sect1>

</chapter>

<!--
local variables: 
sgml-parent-document: ("book.xml" "chapter")
end:
-->

Show details Hide details

Change log

r3306 by cmpilato on Sep 15, 2008 Diff

Tag 1.5 version of the English book (also
known "Version Control With
Subversion, second edition", or "ISBN 10:
0-596-51033-0", or "ISBN 13:
9780596510336", or "Pilato's Bane", or
...)

Go to:

Older revisions

r3301 by cmpilato on Sep 12, 2008 Diff

* src/en/book/ch00-preface.xml,
* src/en/book/ch03-advanced-
topics.xml,
* src/en/book/ch05-repository-
admin.xml,
...

r3293 by cmpilato on Sep 4, 2008 Diff

* src/en/book/ch03-advanced-
topics.xml,
* src/en/book/ch04-branching-and-
merging.xml
  Tweak some wording to avoid implying
...

r3292 by cmpilato on Sep 3, 2008 Diff

* src/en/book/ch09-reference.xml,
* src/en/book/ch03-advanced-
topics.xml,
* src/en/book/appb-svn-for-cvs-
users.xml,
...

All revisions of this file

File info

Size: 191476 bytes, 4094 lines

View raw file

File properties

svn:mime-type: text/xml
svn:eol-style: native