ch07.xml - svnbook - Project Hosting on Google Code

‹r1121

r3653

Source path: svn/ tags/ en-1.0-final/ src/ book/ book/ ch07.xml

<chapter id="svn-ch-7">
  <title>Advanced Topics</title>

  <simplesect id="svn-ch-7-sect-0">

    <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
      checkout 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>
      functions.  You've probably even developed a reflex which 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>.</para>

    <para>This chapter highlights some of Subversion's features that
      aren't quite so regularly used.  In it, we will discuss
      Subversion's property (or <quote>metadata</quote>) support, and
      how to modify Subversion's default behaviors by tweaking its
      run-time configuration area.  We will describe how you can use
      externals definitions to instruct Subversion to pull data from
      multiple repositories.  We'll cover in detail some of the
      additional client- and server-side tools that are part of the
      Subversion distribution.</para>

    <para>Before reading this chapter, you should be familiar with the
      basic file and directory versioning capabilities of Subversion.
      If you haven't already read about those, or if you need a
      refresher, we recommend that you check out <xref
      linkend="svn-ch-2" /> and <xref linkend="svn-ch-3" />.  Once
      you've mastered the basics and consumed this chapter, you'll be
      a Subversion power-user!
    </para>

  </simplesect>

  <!-- ******************************************************************* -->
  <!-- *** SECTION 1:  RUNTIME CONFIGURATION AREA                      *** -->
  <!-- ******************************************************************* -->
  <sect1 id="svn-ch-7-sect-1">
    <title>Runtime Configuration Area</title>
    
    <para>Subversion provides many optional behaviors that can be
      controlled by the user.  Many of these options are of the kind
      that a user would wish to apply to all Subversion operations.
      So, rather than forcing users to remember command-line arguments
      for specifying these options, and to use them for each and every
      operation they perform, Subversion uses configuration files,
      segregated into a Subversion configuration area.</para>

    <para>The Subversion <firstterm>configuration area</firstterm> is
      a two-tiered hierarchy of option names and their values.
      Usually, this boils down to a special directory that contains
      <firstterm>configuration files</firstterm> (the first tier),
      which are just text files in standard INI format (with
      <quote>sections</quote> providing the second tier).  These files
      can be easily edited using your favorite text editor (such as
      Emacs or vi), and contain directives read by the client to
      determine which of several optional behaviors the user
      prefers.</para>

    <!-- ***************************************************************** -->
    <sect2 id="svn-ch-7-sect-1.1">
      <title>Configuration Area Layout</title>

      <para>The first time that the <command>svn</command>
        command-line client is executed, it creates a per-user
        configuration area.  On Unix-like systems, this area appears
        as a directory named <filename>.subversion</filename> in the
        user's home directory.  On Win32 systems, Subversion creates a
        folder named <filename>Subversion</filename>, typically inside
        the <filename>Application Data</filename> area of the user's
        profile directory (which, by the way, is usually a hidden
        directory).  However, on this platform the exact location
        differs from system to system, and is dictated by the Windows
        registry.
        <footnote>
          <para>The <literal>APPDATA</literal> environment variable
            points to the <filename>Application Data</filename> area,
            so you can always refer to this folder as
            <filename>%APPDATA%\Subversion</filename>.</para>
        </footnote>
        We will refer to the per-user configuration area using its Unix
        name, <filename>.subversion</filename>.</para>

      <para>In addition to the per-user configuration area, Subversion
        also recognizes the existence of a system-wide configuration
        area.  This gives system administrators the ability to
        establish defaults for all users on a given machine.  Note
        that the system-wide configuration area does not alone dictate
        mandatory policy&mdash;the settings in the per-user
        configuration area override those in the system-wide one, and
        command-line arguments supplied to the <command>svn</command>
        program have the final word on behavior.  On Unix-like
        platforms, the system-wide configuration area is expected to be
        the <filename>/etc/subversion</filename> directory; on Windows
        machines, it looks for a <filename>Subversion</filename>
        directory inside the common Application Data location (again,
        as specified by the Windows Registry).  Unlike the per-user
        case, the <command>svn</command> program does not attempt to
        create the system-wide configuration area.</para>

      <para>The configuration area currently contains three
        files&mdash;two configuration files (<filename>config</filename> and
        <filename>servers</filename>), and a <filename>README.txt</filename> 
        file which describes the INI format.  At the time of their
        creation, the files contain default values for each of the
        supported Subversion options, mostly commented out and grouped
        with textual descriptions about how the values for the key
        affect Subversion's behavior.  To change a certain behavior,
        you need only to load the appropriate configuration file into
        a text editor, and modify the desired option's value.  If at
        any time you wish to have the default configuration settings
        restored, you can simply remove (or rename) your configuration
        directory and then run some innocuous <command>svn</command>
        command, such as <command>svn --version</command>.  A new
        configuration directory with the default contents will be
        created.</para>

      <para>The per-user configuration area also contains a cache of
        authentication data.  The <filename>auth</filename> directory
        holds a set of subdirectories that contain pieces of cached
        information used by Subversion's various supported
        authentication methods.  This directory is created in such a
        way that only the user herself has permission to read its
        contents.</para>

    </sect2>

    <!-- ***************************************************************** -->
    <sect2 id="svn-ch-7-sect-1.2">
      <title>Configuration and the Windows Registry</title>

      <para>In addition to the usual INI-based configuration area,
        Subversion clients running on Windows platforms may also use
        the Windows registry to hold the configuration data.  The
        option names and their values are the same as in the INI
        files.  The <quote>file/section</quote> hierarchy is
        preserved as well, though addressed in a slightly different
        fashion&mdash;in this schema, files and sections are just
        levels in the registry key tree.</para>

      <para>Subversion looks for system-wide configuration values
        under the
        <literal>HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion</literal>
        key.  For example, the <literal>global-ignores</literal> option,
        which is in the <literal>miscellany</literal> section of the
        <filename>config</filename> file, would be found at
        <literal>HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion\Config\Miscellany\global-ignores</literal>.
        Per-user configuration values should be stored under
        <literal>HKEY_CURRENT_USER\Software\Tigris.org\Subversion</literal>.
      </para>

      <para>Registry-based configuration options are parsed
        <emphasis>before</emphasis> their file-based counterparts,
        so are overridden by values found in the configuration
        files.  In other words, configuration priority is granted in
        the following order on a Windows system:</para>
      
      <orderedlist>
        <listitem>
          <para>Command-line options</para>
        </listitem>
        <listitem>
          <para>The per-user INI files</para>
        </listitem>
        <listitem>
          <para>The per-user Registry values</para>
        </listitem>
        <listitem>
          <para>The system-wide INI files</para>
        </listitem>
        <listitem>
          <para>The system-wide Registry values</para>
        </listitem>
      </orderedlist>

      <para>Also, the Windows Registry doesn't really support the
        notion of something being <quote>commented out</quote>.
        However, Subversion will ignore any option key whose name
        begins with a hash (<literal>#</literal>) character.  This
        allows you to effectively comment out a Subversion option
        without deleting the entire key from the Registry, obviously
        simplifying the process of restoring that option.</para>

      <para>The <command>svn</command> command-line client never
        attempts to write to the Windows Registry, and will not
        attempt to create a default configuration area there.  You can
        create the keys you need using the <command>REGEDIT</command>
        program.  Alternatively, you can create a
        <filename>.reg</filename> file, and then double-click on that
        file from the Explorer shell, which will cause the data to be
        merged into your registry.</para>

      <example id="svn-ch-7-sect-1.2-ex-1">
        <title>Sample Registration Entries (.reg) File.</title>


        <programlisting>
REGEDIT4

[HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion\Servers\groups]

[HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion\Servers\global]
"#http-proxy-host"=""
"#http-proxy-port"=""
"#http-proxy-username"=""
"#http-proxy-password"=""
"#http-proxy-exceptions"=""
"#http-timeout"="0"
"#http-compression"="yes"
"#neon-debug-mask"=""
"#ssl-authority-files"=""
"#ssl-trust-default-ca"=""
"#ssl-client-cert-file"=""
"#ssl-client-cert-password"=""

[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\auth]
"#store-auth-creds"="no"

[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\helpers]
"#editor-cmd"="notepad"
"#diff-cmd"=""
"#diff3-cmd"=""
"#diff3-has-program-arg"=""

[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\miscellany]
"#global-ignores"="*.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#*"
"#log-encoding"=""
"#use-commit-times"=""
"#template-root"=""
"#enable-auto-props"=""

[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\tunnels]

[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\auto-props]
</programlisting>
      </example>

      <para>The previous example shows the contents of a
        <filename>.reg</filename> file which contains some of the most
        commonly used configuration options and their default values.
        Note the presence of both system-wide (for network
        proxy-related options) and per-user settings (editor programs
        and password storage, among others).  Also note that all the
        options are effectively commented out.  You need only to
        remove the hash (<literal>#</literal>) character from the
        beginning of the option names, and set the values as you
        desire.</para>

    </sect2>

    <!-- ***************************************************************** -->
    <sect2 id="svn-ch-7-sect-1.3">
      <title>Configuration Options</title>
      
      <para>In this section, we will discuss the specific
        run-time configuration options that are currently supported
        by Subversion.</para>

      <sect3 id="svn-ch-7-sect-1.3.1">
        <title>Servers</title>

        <para>The <filename>servers</filename> file contains
          Subversion configuration options related to the network
          layers.  There are two special section names in this
          file&mdash;<literal>groups</literal> and
          <literal>global</literal>.  The <literal>groups</literal>
          section is essentially a cross-reference table.  The keys in
          this section are the names of other sections in the file;
          their values are <firstterm>globs</firstterm>&mdash;textual
          tokens which possibly contain wildcard
          characters&mdash;that are compared against the hostnames of
          the machine to which Subversion requests are sent.</para>

        <programlisting>
[groups]
beanie-babies = *.red-bean.com
collabnet = svn.collab.net

[beanie-babies]
&hellip;

[collabnet]
&hellip;
</programlisting>

        <para>When Subversion is used over a network, it attempts to
          match the name of the server it is trying to reach with a
          group name under the <literal>groups</literal> section.  If
          a match is made, Subversion then looks for a section in the
          <filename>servers</filename> file whose name is the matched
          group's name.  From that section it reads the actual network
          configuration settings.</para>

        <para>The <literal>global</literal> section contains the
          settings that are meant for all of the servers not matched
          by one of the globs under the <literal>groups</literal>
          section.  The options available in this section are
          exactly the same as those valid for the other server
          sections in the file (except, of course, the special
          <literal>groups</literal> section), and are as
          follows:</para>

        <variablelist>
          <varlistentry>
            <term><literal>http-proxy-host</literal></term>
            <listitem>
              <para>This specifies the hostname of the proxy computer
                through which your HTTP-based Subversion requests must
                pass.  It defaults to an empty value, which means that
                Subversion will not attempt to route HTTP requests
                through a proxy computer, and will instead attempt to
                contact the destination machine directly.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><literal>http-proxy-port</literal></term>
            <listitem>
              <para>This specifies the port number on the proxy host
                to use.  It defaults to an empty value.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><literal>http-proxy-username</literal></term>
            <listitem>
              <para>This specifies the username to supply to the proxy
                machine.  It defaults to an empty value.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><literal>http-proxy-password</literal></term>
            <listitem>
              <para>This specifies the password to supply to the proxy
                machine.  It defaults to an empty value.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><literal>http-timeout</literal></term>
            <listitem>
              <para>This specifies the amount of time, in seconds, to
                wait for a server response.  If you experience
                problems with a slow network connection causing
                Subversion operations to timeout, you should increase
                the value of this option.  The default value is
                <literal>0</literal>, which instructs the underlying
                HTTP library, Neon, to use its default timeout
                setting.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><literal>http-compression</literal></term>
            <listitem>
              <para>This specifies whether or not Subversion should
                attempt to compress network requests made to DAV-ready
                servers.  The default value is <literal>yes</literal>
                (though compression will only occur if that capability
                is compiled into the network layer).  Set this to
                <literal>no</literal> to disable compression, such as
                when debugging network transmissions.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><literal>neon-debug-mask</literal></term>
            <listitem>
              <para>This is an integer mask that the underlying HTTP
                library, Neon, uses for choosing what type of
                debugging output to yield.  The default value is
                <literal>0</literal>, which will silence all debugging
                output.  For more information about how Subversion
                makes use of Neon, see <xref linkend="svn-ch-8" />.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><literal>ssl-authority-files</literal></term>
            <listitem>
              <para>This is a semicolon-delimited list of paths to files
                containing certificates of the certificate authorities
                (or CAs) that
                are accepted by the Subversion client when accessing the
                repository over HTTPS.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><literal>ssl-trust-default-ca</literal></term>
            <listitem>
              <para>Set this variable to <literal>yes</literal> if you
                want Subversion to automatically trust the set of
                default CAs that ship with OpenSSL.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><literal>ssl-client-cert-file</literal></term>
            <listitem>
              <para>If a host (or set of hosts) requires an SSL client
                certificate, you'll normally be prompted for a path to
                your certificate.  By setting this variable to that
                same path, Subversion will be able to find your client
                certificate automatically without prompting you.
                There's no standard place to store your certificate on
                disk; Subversion will grab it from any path you
                specify.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><literal>ssl-client-cert-password</literal></term>
            <listitem>
              <para>If your SSL client certificate file is encrypted
                by a passphrase, Subversion will prompt you for the
                passphrase whenever the certificate is used.  If you
                find this annoying (and don't mind storing the
                password in the <filename>servers</filename> file),
                then you can set this variable to the certificate's
                passphrase.  You won't be prompted anymore.</para>
            </listitem>
          </varlistentry>
        </variablelist>


      </sect3>
      <sect3 id="svn-ch-7-sect-1.3.2">
        <title>Config</title>

        <para>The <filename>config</filename> file contains the rest
          of the currently available Subversion run-time options,
          those not related to networking.  There are only a few
          options in use at this time, but they are again grouped into
          sections in expectation of future additions.</para>

        <para>The <literal>auth</literal> section contains settings
          related to Subversion's authentication and authorization
          against the repository.  It contains:</para>

        <variablelist>
          <varlistentry>
            <term><literal>store-auth-creds</literal></term>
            <listitem>
              <para>This instructs Subversion to cache, or not to
                cache, authentication credentials that are supplied by
                the user in response to server authentication
                challenges.  The default value is
                <literal>yes</literal>.  Set this to
                <literal>no</literal> to disable this on-disk
                credential caching.  You can override this option for
                a single instance of the <command>svn</command>
                command using the <option>--no-auth-cache</option>
                command-line parameter (for those subcommands that
                support it).  For more information, see <xref
                linkend="svn-ch-6-sect-2.2"/>.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <para>The <literal>helpers</literal> section controls which
          external applications Subversion uses to accomplish its
          tasks.  Valid options in this section are:</para>

        <variablelist>
          <varlistentry>
            <term><literal>editor-cmd</literal></term>
            <listitem>
              <para>This specifies the program Subversion will use to
                query the user for a log message during a commit
                operation, such as when using <command>svn
                commit</command> without either the
                <option>--message</option> (<option>-m</option>) or
                <option>--file</option> (<option>-F</option>) options.
                This program is also used with the <command>svn
                propedit</command> command&mdash;a temporary file is
                populated with the current value of the property the
                user wishes to edit, and the edits take place right
                in the editor program (see <xref
                linkend="svn-ch-7-sect-2" />).  This option's default
                value is empty.  If the option is not set, Subversion
                will fall back to checking the environment variables
                <literal>SVN_EDITOR</literal>,
                <literal>VISUAL</literal>, and
                <literal>EDITOR</literal> (in that order) for an
                editor command.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><literal>diff-cmd</literal></term>
            <listitem>
              <para>This specifies the absolute path of a differencing
                program, used when Subversion generates
                <quote>diff</quote> output (such as when using the
                <command>svn diff</command> command).  By default
                Subversion uses an internal differencing
                library&mdash;setting this option will cause it to
                perform this task using an external program.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><literal>diff3-cmd</literal></term>
            <listitem>
              <para>This specifies the absolute path of a three-way
                differencing program.  Subversion uses this program to
                merge changes made by the user with those received
                from the repository.  By default Subversion uses an
                internal differencing library&mdash;setting this
                option will cause it to perform this task using an
                external program.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><literal>diff3-has-program-arg</literal></term>
            <listitem>
              <para>This flag should be set to <literal>true</literal>
              if the program specified by the
              <literal>diff3-cmd</literal> option accepts a
              <option>--diff-program</option> command-line
              parameter.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <para>The <literal>tunnels</literal> section allows you to
          define new tunnel schemes for use with
          <command>svnserve</command> and <literal>svn://</literal>
          client connections.  For more details, see <xref
          linkend="svn-ch-6-sect-3.3"/>.</para>

        <para>The <literal>miscellany</literal> section is where
          everything that doesn't belong elsewhere winds up.
          <footnote>
            <para>Anyone for potluck dinner?</para> 
          </footnote>
          In this section, you can find:</para>

        <variablelist>
          <varlistentry>
            <term><literal>global-ignores</literal></term>
            <listitem>
              <para>When running the <command>svn status</command>
                command, Subversion lists unversioned files and
                directories along with the versioned ones, annotating
                them with a <literal>?</literal> character (see <xref
                linkend="svn-ch-3-sect-4.3.1" />).  Sometimes, it can
                be annoying to see uninteresting, unversioned
                items&mdash;for example, object files that result from
                a program's compilation&mdash;in this display.  The
                <literal>global-ignores</literal> option is a list of
                whitespace-delimited globs which describe the names of
                files and directories that Subversion should not
                display unless they are versioned.  The default value
                is <literal>*.o *.lo *.la #*# .*.rej *.rej .*~ *~
                .#*</literal>.</para>

              <para>You can override this option for a single instance
                of the <command>svn status</command> command by using
                the <option>--no-ignore</option> command-line flag.
                For information on more fine-grained control of
                ignored items, see <xref linkend="svn-ch-7-sect-2.3.3"
                />.</para>
            </listitem>
          </varlistentry>
          
          <varlistentry>
            <term><literal>enable-auto-props</literal></term>
            <listitem>
              <para>This instructs Subversion to automatically set
                properties on newly added or imported files.  The
                default value is <literal>no</literal>, so set this to
                <literal>yes</literal> to enable Auto-props.</para>

              <para>The <literal>auto-props</literal> section controls
                the Subversion client's ability to automatically set
                properties on files when they are added or imported.
                It contains any number of key-value pairs in the
                format <literal>PATTERN = PROPNAME=PROPVALUE</literal>
                where <literal>PATTERN</literal> is a file pattern
                that matches a set of filenames and the rest of the
                line is the property and its value.  Multiple matches
                on a file will result in multiple propsets for that
                file; however, there is no guarantee that auto-props
                will be applied in the order in which they are listed
                in the config file, so you can't have one rule
                <quote>override</quote> another.  You can find several
                examples of auto-props usage in the
                <filename>config</filename> file.  Lastly, don't
                forget to set <literal>enable-auto-props</literal> to
                <literal>yes</literal> if you want to enable
                auto-props. </para>
            </listitem>            
          </varlistentry>

          <varlistentry>
            <term><literal>log-encoding</literal></term>
            <listitem>         
              <para>This variable sets the default character set
                encoding for commit log messages.  It's a permanent
                form of the <option>--encoding</option> option (see
                <xref linkend="svn-ch-9-sect-1.1"/>.)  The Subversion
                repository stores log messages in UTF8, and assumes
                that your log message is written using your operating
                system's native locale.  You should specify a
                different encoding if your commit messages are written
                in any other encoding.</para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term><literal>use-commit-times</literal></term>
            <listitem>         
              <para>Normally your working copy files have timestamps
                that reflect the last time they were touched by any
                process, whether that be your own editor or by some
                <command>svn</command> subcommand.  This is generally
                convenient for people developing software, because
                build systems often look at timestamps as a way of
                deciding which files need to be recompiled.</para>

              <para>In other situations, however, it's sometimes nice
                for the working copy files to have timestamps that
                reflect the last time they were changed in the
                repository.  The <command>svn export</command> command
                always places these <quote>last-commit
                timestamps</quote> on trees that it produces.  By
                setting this config variable to
                <literal>yes</literal>, the <command>svn
                checkout</command>, <command>svn update</command>,
                <command>svn switch</command>, and <command>svn
                revert</command> commands will also set last-commit
                timestamps on files that they touch.</para>
            </listitem>
          </varlistentry>
          
	  <!-- ###TODO add description of other options shown in example
          registry file, e.g., log-encoding, etc. -->
        </variablelist>


      </sect3>

    </sect2>
  </sect1>

  <!-- ******************************************************************* -->
  <!-- *** SECTION 2:  PROPERTIES                                      *** -->
  <!-- ******************************************************************* -->
  <sect1 id="svn-ch-7-sect-2">
    <title>Properties</title>

    <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.  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 be
      human-readable text.  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 committing textual changes.  And you
      receive other people's property changes as you update your
      working copy.</para>

    <sidebar>
      <title>Other Properties in Subversion</title>

      <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, text names and anything-you-want,
        binary values&mdash;except that revision properties are not
        versioned.  See <xref linkend="svn-ch-5-sect-1.2" /> for more
        information on these unversioned properties.</para>
    </sidebar>

    <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.
      Hopefully, you'll be convinced that Subversion properties can
      enhance your version control experience.</para>

    <!-- ***************************************************************** -->
    <sect2 id="svn-ch-7-sect-2.1">
      <title>Why Properties?</title>

      <para>Properties can be very useful additions to your working
        copy.  In fact, Subversion itself uses properties to house
        special information, and as a way to denote that certain
        special processing might be needed.  Likewise, you can use
        properties for your own purposes.  Of course, anything you can
        do with properties you could also do using regular versioned
        files, but consider the following example of Subversion
        property use.</para>

      <para>Say you wish to design a website 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.  You can do this with 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, like
        <filename>thumbnails/image123.jpg</filename>.  You can also
        store your captions and datestamps in a similar fashion, again
        separated from the original image file.  Soon, your tree of
        files is a mess, and grows in multiples with each new photo
        added to the site.</para>

     <para>Now consider the same setup using Subversion's file
        properties.  Imagine having a single image file,
        <filename>image123.jpg</filename>, and then properties set on
        that file 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 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-ch-8-sect-2.3" />) 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>

      <para>How (and if) you use Subversion properties is up to you.
        As we mentioned, Subversion has it own uses for properties,
        which we'll discuss a little later in this chapter.  But
        first, let's discuss how to manipulate options using the
        <command>svn</command> program.</para>

    </sect2>

    <!-- ***************************************************************** -->
    <sect2 id="svn-ch-7-sect-2.2">
      <title>Manipulating Properties</title>

      <para>The <command>svn</command> command 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>propset</command>
        subcommand.</para>

      <screen>
$ svn propset copyright '(c) 2003 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 multi-line textual, or even binary, property value, you
        probably do not want to supply that value on the command-line.
        So the <command>propset</command> subcommand takes a
        <option>--file</option> (<option>-F</option>) option for
        specifying the name of
        a file which 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>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-ch-7-sect-1.3.2" />) 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 which 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:</para>

      <screen>
$ svn propset copyright '(c) 2002 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 path (or set of
        paths) and a property name, 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) 2003 Red-Bean Software
</screen>


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

      <screen>
$ svn proplist --verbose calc/button.c
Properties on 'calc/button.c':
  copyright : (c) 2003 Red-Bean Software
  license : ================================================================
Copyright (c) 2003 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>propedit</command> or
        <command>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 --verbose calc/button.c
Properties on 'calc/button.c':
  copyright : (c) 2003 Red-Bean Software
  license : 
$
</screen>

      <para>You need to use the <command>propdel</command> command 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 ''.
$ svn proplist --verbose calc/button.c
Properties on 'calc/button.c':
  copyright : (c) 2003 Red-Bean Software
$
</screen>

      <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;in cleanly or conflicting fashions&mdash;someone
        else's modifications into your own.</para>

      <sidebar>
        <title>Modifying Revision Properties</title>

        <para>Remember those unversioned revision properties?  You can
          modify those, too, with the <command>svn</command> program.
          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 path in this case as long as you are positioned in
          the working copy of the repository whose revision property
          you wish to modify.  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></para>

        <screen>
$ svn propset svn:log '* button.c: Fix a compiler warning.' -r11 --revprop
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-ch-5-sect-2.1" />).
          Since the properties aren't versioned, you run the risk of
          losing information if you aren't careful with your edits.
          The repository administrator can setup methods to protect
          against this loss, and by default, modification of
          unversioned properties is disabled.</para>

      </sidebar>

      <para>And as with file contents, your property changes are local
        modifications, only made permanent 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 un-edited states, 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) 2003 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 modified its
        textual contents.  Had we changed both, we would have seen
        <literal>M</literal> in the first column, too (see <xref
        linkend="svn-ch-3-sect-4.3.1" />).</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 resource that clash with your own,
          Subversion will report that the resource is in a conflicted
          state.</para>
 
        <screen>
% svn update calc
M  calc/Makefile.in
 C calc/button.c
Updated to revision 143.
$ 
</screen>
         
        <para>Subversion will also create, in the same directory as
          the conflicted resource, a file with a
          <filename>.prej</filename> extension which 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 resource, 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 
prop 'linecount': user set to '1256', but update set to '1301'.
$
</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 non-standard way that
        Subversion currently displays property differences.  You can
        still run <command>svn diff</command> and redirect the 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>

      <para>As you can see, the presence of property modifications has
        no outstanding effect on the typical Subversion workflow.
        Your general patterns of updating your working copy, checking
        the status of your files and directories, reporting on the
        modifications you have made, and committing those
        modifications to the repository are completely immune to the
        presence or absence of properties.  The <command>svn</command>
        program has some additional subcommands for actually making
        property changes, but that is the only noticeable asymmetry.</para>

    </sect2>

    <!-- ***************************************************************** -->
    <sect2 id="svn-ch-7-sect-2.3">
      
      <title>Special Properties</title>


      <para>Subversion has no particular policy regarding
        properties&mdash;you can use them for any purpose.  Subversion
        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.  In fact, Subversion defines
        certain properties that have magical effects on the files and
        directories to which they are attached.  In this section,
        we'll untangle the mystery, and describe how these special
        properties make your life just a little easier.</para>
      
      <sect3 id="svn-ch-7-sect-2.3.1">
        <title><literal>svn:executable</literal></title>
 
        <para>The <literal>svn:executable</literal> property is used
          to control a versioned file's filesystem-level execute
          permission bit in a semi-automated way.  This property has
          no defined values&mdash;its mere presence indicates a desire
          that the execute permission bit be kept enabled by Subversion.
          Removing this property will restore full control of the
          execute bit back to the operating system.</para>

        <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.  In a working copy, new files are
          being created all the time as new versions of existing files
          are received during an update.  This means that you might
          enable the execute bit on a file, then update your working
          copy, and if that file was changed as part of the update,
          its execute bit might get disabled.  So, Subversion provides
          the <literal>svn:executable</literal> property as a way to
          keep the execute bit enabled.</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
              <literal>.EXE</literal>, <literal>.BAT</literal>, and
              <literal>.COM</literal>) 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>

      </sect3>

      <sect3 id="svn-ch-7-sect-2.3.2">
        <title><literal>svn:mime-type</literal></title>
        
        <para>The <literal>svn:mime-type</literal> property serves
          many purposes in Subversion.  Besides being a
          general-purpose storage location for a file's Multipurpose
          Internet Mail Extensions (MIME) classification, the value of
          this property determines some behavioral characteristics
          of Subversion itself.</para>

        <para>For example, if a file's
          <literal>svn:mime-type</literal> property is set to a
          non-text MIME type (generally, something that doesn't begin
          with <literal>text/</literal>, though there are exceptions),
          Subversion will assume that the file contains
          binary&mdash;that is, not human-readable&mdash;data.  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 believed to contain binary data, there is no concept
          of a <quote>line</quote>.  So, for those files, 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 renamed with a <filename>.orig</filename> extension,
          and then Subversion stores a new working copy file that
          contains the changes received during the update, but not
          your own local modifications, at the original filename.
          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>

        <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 a
          crucial clue about how to display a file when perusing
          your repository with a web browser.</para>

      </sect3>

      <sect3 id="svn-ch-7-sect-2.3.3">
        <title><literal>svn:ignore</literal></title>

        <para>The <literal>svn:ignore</literal> property contains a
          list of file patterns which certain Subversion operations
          will ignore.  Perhaps the most commonly used special
          property, it works in conjunction with the
          <literal>global-ignores</literal> run-time configuration
          option (see <xref linkend="svn-ch-7-sect-1.3.2" />) to
          filter unversioned files and directories out of commands
          like <command>svn status</command>, <command>svn
          add</command>, and <command>svn import</command>.</para>

        <para>The rationale behind the <literal>svn:ignore</literal>
          property is easily explained.  Subversion does not assume
          that every file or subdirectory in a working copy directory
          is intended for version control.  Resources must be
          explicitly placed under Subversion's management using the
          <command>svn add</command> or <command>svn import</command>
          commands.  As a result, there are often many resources in a
          working copy that are not versioned.</para>

        <para>Now, the <command>svn status</command> command displays
          as part of its output every unversioned file or subdirectory
          in a working copy that is not already filtered out by the
          <literal>global-ignores</literal> option (or its built-in
          default value).  This is done so that users can see if
          perhaps they've forgotten to add a resource to version
          control.</para>

       <para>But Subversion cannot possibly guess the names of
          every resource that should be ignored.  Also, quite often
          there are things that should be ignored in
          <emphasis>every</emphasis> working copy of a particular
          repository.  To force every user of that repository to add
          patterns for those resources to their run-time configuration
          areas would be not just a burden, but has the potential to
          clash with the configuration needs of other working copies
          that the user has checked out.</para>

        <para>The solution is to store ignore patterns that are unique
          to the resources likely to appear in a given directory with
          the directory itself.  Common examples of unversioned
          resources that are basically unique to a directory, yet
          likely to appear there, include output from program
          compilations.  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>

        <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>For this purpose, the <literal>svn:ignore</literal>
          property is the solution.  Its value is a multi-line
          collection of file patterns, one pattern per line.  The
          property is set on the directory in which you wish the
          patterns to be applied.
          <footnote>
            <para>The patterns are strictly for that
              directory&mdash;they do not carry recursively into
              subdirectories.</para>
          </footnote>
          For example, 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 log files.  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 log files lying around.  These facts are true for
          all working copies, not just your own.  And you know that
          you aren't interested in seeing those things every time you
          run <command>svn status</command>.  So you use <command>svn
          propedit svn:ignore calc</command> 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 the cruft is missing from the output!  Of
          course, those files are still in your working copy.
          Subversion is simply not reminding you that they are present
          and unversioned.  And now with all the trivial noise removed
          from the display, you are left with more interesting
          items&mdash;such as that source code file that you probably
          forgot to add to version control.</para>

        <para>If you want to see the ignored files, you can pass the 
          <command>--no-ignore</command> option to subversion:</para>

<screen>
$ svn status --no-ignore
 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>The list of 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 to determine which files
          should not be swept into the version control system as part
          of a larger recursive addition or import operation.</para>
   
      </sect3>

      <sect3 id="svn-ch-7-sect-2.3.4">
        <title><literal>svn:keywords</literal></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 describe
          information about the last time the file was known to be
          modified.  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>Subversion defines the list of keywords available for
          substitution.  That list contains the following five
          keywords, some of which have shorter aliases that you can
          also use:</para>

        <variablelist>
          <varlistentry>
            <term><literal>LastChangedDate</literal></term>
            <listitem>
              <para>This keyword describes the last time the file was
                known to have been changed in the repository, and
                looks something like <literal>$LastChangedDate:
                2002-07-22 21:42:37 -0700 (Mon, 22 Jul 2002)
                $</literal>.  It may be abbreviated as
                <literal>Date</literal>.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><literal>LastChangedRevision</literal></term>
            <listitem>
              <para>This keyword describes the last known revision in
                which this file changed in the repository, and looks
                something like <literal>$LastChangedRevision: 144
                $</literal>.  It may be abbreviated as
                <literal>Revision</literal> or
                <literal>Rev</literal>.</para>
            </listitem>
          </varlistentry>
          <varlistentry>
            <term><literal>LastChangedBy</literal></term>
            <listitem>
              <para>This keyword describes the last known user to
                change this file in the repository, and looks
                something like <literal>$LastChangedBy: harry
                $</literal>.  It may be abbreviated as
                <literal>Author</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 2002-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, 2002 by the user
                <literal>sally</literal>.</para>
            </listitem>
          </varlistentry>
        </variablelist>

        <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 un-substituted keyword
          anchors!</para>

        <para>To tell Subversion whether or not 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 the keyword names or aliases found in the previous
          table.</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 "LastChangedDate 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>

        <sidebar>
          <title>Keywords and Spurious Differences</title>

          <para>The user-visible result of keyword substitution might
            lead you to think that every version of a file with that
            feature in use differs from the previous version in at
            least the area where the keyword anchor was placed.
            However, this is actually not the case.  While checking
            for local modifications during <command>svn
            diff</command>, and before transmitting those local
            modifications during <command>svn commit</command>,
            Subversion <quote>un-substitutes</quote> any keywords that
            it previously substituted.  The result is that the
            versions of the file that are stored in the repository
            contain only the real modifications that users make to the
            file.</para>


        </sidebar>

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

        <screen>
Here is the latest report from the front lines.
$LastChangedDate: 2002-07-22 21:42:37 -0700 (Mon, 22 Jul 2002) $
$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 re-substituted with information that
          reflects the most recent known commit to that file.</para>

      </sect3>

      <sect3 id="svn-ch-7-sect-2.3.5">
        <title><literal>svn:eol-style</literal></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 only uses this knowledge to determine
          if 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 system use different tokens to 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;carriage return
          (<literal>CR</literal>) and 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
          are prepared to 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.  Common results are that Unix programs
          treat the <literal>CR</literal> character present in Windows
          files as a regular character (usually rendered as
          <literal>^M</literal>), and that 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 end of
          line.</para>

        <para>This sensitivity to foreign EOL markers can become
          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 which
          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 they
          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 non-trivial 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 which 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.  It was used on older
                Macintosh platforms (on which Subversion doesn't even
                run).</para>
            </listitem>
          </varlistentry>
        </variablelist>
        
      </sect3>

      <sect3 id="svn-ch-7-sect-2.3.6">
        <title><literal>svn:externals</literal></title>

        <para>The <literal>svn:externals</literal> property contains
          instructions for Subversion to populate a versioned
          directory with one or more other checked-out Subversion
          working copies.  For more information on this keyword and
          its use, see <xref linkend="svn-ch-7-sect-3"/>.</para>

      </sect3>
    </sect2>

    <!-- ***************************************************************** -->
    <sect2 id="svn-ch-7-sect-2.4">
      <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, etc.  But
        to get the full benefit of properties, they must be set on the
        right files and directories.  Unfortunately, that can be a
        step easily forgotten in the routine of things, especially
        since failing to set a property doesn't usually result in an
        obvious error condition (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 runs a very basic heuristic to determine
        if that file consists of human-readable or non-human-readable
        content.  If the latter is the decision made, Subversion will
        automatically set 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.</para>


      <para>Subversion also provides the auto-props feature, which
        allows you to create mappings of filename patterns to property
        names and values.  These mappings are made in your runtime
        configuration area.  They again affect adds and imports, and
        not only can override any default MIME type decision made by
        Subversion during those operations, they can also set
        additional Subversion or custom properties, too.  For example,
        you might create a mapping that says that any time you add
        JPEG files&mdash;ones that 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>.  Auto-prop support is perhaps
        the handiest property related tool in the Subversion toolbox.
        See <xref linkend="svn-ch-7-sect-1.3.2"/> for more about
        configuring that support.</para>

    </sect2>     
  </sect1>

  <!-- ******************************************************************* -->
  <!-- *** SECTION 3:  EXTERNALS DEFINITIONS                           *** -->
  <!-- ******************************************************************* -->
  <sect1 id="svn-ch-7-sect-3">
    <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 setup 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 possibly a particular revision&mdash;of a
      versioned resource.  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-ch-7-sect-2.1"/>).  
      It can be set on any versioned directory,
      and its value is a multi-line table of subdirectories (relative
      to the versioned directory on which the property is set) and
      fully qualified, absolute Subversion repository URLs.</para>

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

    <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 those nested
      working copy checkouts, no one else has to
      bother&mdash;Subversion will, upon checkout of the original
      working copy, also checkout the external working copies.</para>

    <para>Note the previous externals definition example.  When
      someone checks out a working copy of the
      <filename>calc</filename> directory, Subversion also continues
      to checkout 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>If you need to change the 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
      <command>svn update</command>.  The same thing will happen when
      others update their working copies and receive your changes to
      the externals definition.</para>

    <para>The <command>svn status</command> command also recognizes
      externals definitions, displaying a status code of
      <literal>X</literal> for the disjoint subdirectories into which
      externals are checked out, and then recursing into those
      subdirectories to display the status of the external items
      themselves.</para>

    <para>The support that exists for externals definitions in
      Subversion today can be a little misleading, though.  First, an
      externals definition can only point to directories, not files.
      Second, the externals definition cannot point to relative paths
      (paths like <filename>../../skins/myskin</filename>).  Third, 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 only truly
      operates on non-disjoint 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>Also, since the definitions themselves 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
      renamed directory).  This can be confusing&mdash;even
      frustrating&mdash;in certain situations.  For example, if you
      use externals definitions on a directory in your
      <filename>/trunk</filename> development line which point to
      other areas of that same line, and then you use <command>svn
      copy</command> to branch that line to some new location
      <filename>/branches/my-branch</filename>, the externals
      definitions on items in your new branch will still refer to
      versioned resources in <filename>/trunk</filename>.  Also, be
      aware that if you need to re-parent your working copy (using
      <command>svn switch --relocate</command>), externals definitions
      will <emphasis>not</emphasis> also be re-parented.</para>

  </sect1>

  <!-- ******************************************************************* -->
  <!-- *** SECTION 4:  VENDOR BRANCHES                                 *** -->
  <!-- ******************************************************************* -->
  <sect1 id="svn-ch-7-sect-4">
    <title>Vendor branches</title>

    <para>As is especially the case when developing software, the data
      that you maintain under version control is often closely related
      to, or perhaps dependent upon, someone else's data.  Generally,
      the needs of your project will dictate that you stay as
      up-to-date as possible with the data provided by that external
      entity without sacrificing the stability of your own project.
      This scenario plays itself out all the time&mdash;anywhere that
      the information generated by one group of people has a direct
      effect on that which is generated by another group.</para>
 
    <para>For example, software developers might be working on an
      application which makes use of a third-party library.
      Subversion has just such a relationship with the Apache Portable
      Runtime library (see <xref linkend="svn-ch-8-sect-2.1" />).  The
      Subversion source code depends on the APR library for all its
      portability needs.  In earlier stages of Subversion's
      development, the project closely tracked APR's changing API,
      always sticking to the <quote>bleeding edge</quote> of the
      library's code churn.  Now that both APR and Subversion have
      matured, Subversion attempts to synchronize with APR's library
      API only at well-tested, stable release points.</para>

    <para>Now, if your project depends on someone else's information,
      there are several ways that you could attempt to synchronize that
      information with your own.  Most painfully, you could issue oral
      or written instructions to all the contributors of your project,
      telling them to make sure that they have the specific versions
      of that third-party information that your project needs.  If the
      third-party information is maintained in a Subversion
      repository, you could also use Subversion's externals
      definitions to effectively <quote>pin down</quote> specific
      versions of that information to some location in your own
      working copy directory (see <xref linkend="svn-ch-7-sect-3" />).</para>

    <para>But sometimes you want to maintain custom modifications to
      third-party data in your own version control system.  Returning
      to the software development example, programmers might need to
      make modifications to that third-party library for their own
      purposes.  These modifications might include new functionality
      or bug fixes, maintained internally only until they become part
      of an official release of the third-party library.  Or the
      changes might never be relayed back to the library maintainers,
      existing solely as custom tweaks to make the library further
      suit the needs of the software developers.</para>

    <para>Now you face an interesting situation.  Your project could
      house its custom modifications to the third-party data in some
      disjointed fashion, such as using patch files or full-fledged
      alternate versions of files and directories.  But these quickly
      become maintenance headaches, requiring some mechanism by which
      to apply your custom changes to the third-party data, and
      necessitating regeneration of those changes with each successive
      version of the third-party data that you track.</para>


    <para>The solution to this problem is to use <firstterm>vendor
      branches</firstterm>.  A vendor branch is a directory tree in
      your own version control system that contains information
      provided by a third-party entity, or vendor.  Each version of
      the vendor's data that you decide to absorb into your project is
      called a <firstterm>vendor drop</firstterm>.</para> 

    <para>Vendor branches provide two key benefits.  First, by storing
      the currently supported vendor drop in your own version control
      system, the members of your project never need to question
      whether they have the right version of the vendor's data.  They
      simply receive that correct version as part of their regular
      working copy updates.  Secondly, because the data lives in your
      own Subversion repository, you can store your custom changes to
      it in-place&mdash;you have no more need of an automated (or
      worse, manual) method for swapping in your customizations.</para>

    <!-- ***************************************************************** -->
    <sect2 id="svn-ch-7-sect-4.1">
      <title>General Vendor Branch Management Procedure</title>

      <para>Managing vendor branches generally works like this.  You
        create a top-level directory (such as
        <filename>/vendor</filename>) to hold the vendor branches.
        Then you import the third party code into a subdirectory of
        that top-level directory.  You then copy that subdirectory
        into your main development branch (for example,
        <filename>/trunk</filename>) at the appropriate location.  You
        always make your local changes in the main development branch.
        With each new release of the code you are tracking you bring
        it into the vendor branch and merge the changes into
        <filename>/trunk</filename>, resolving whatever conflicts
        occur between your local changes and the upstream
        changes.</para>

      <para>Perhaps an example will help to clarify this algorithm.
        We'll use a scenario where your development team is creating a
        calculator program that links against a third-party complex
        number arithmetic library, libcomplex.  We'll begin with the
        initial creation of the vendor branch, and the import of the
        first vendor drop.  We'll call our vendor branch directory
        <filename>libcomplex</filename>, and our code drops will go
        into a subdirectory of our vendor branch called
        <filename>current</filename>.  And since <command>svn
        import</command> creates all the intermediate parent
        directories it needs, we can actually accomplish both of these
        steps with a single command.</para>

      <screen>
$ svn import /path/to/libcomplex-1.0 \
             http://svn.example.com/repos/vendor/libcomplex/current \
             -m 'importing initial 1.0 vendor drop'
&hellip;
</screen>
    
      <para>We now have the current version of the libcomplex source
        code in <filename>/vendor/libcomplex/current</filename>.  Now,
        we tag that version (see <xref linkend="svn-ch-4-sect-6" />)
        and then copy it into the main development branch.  Our copy
        will create a new directory called
        <filename>libcomplex</filename> in our existing
        <filename>calc</filename> project directory.  It is in this
        copied version of the vendor data that we will make our
        customizations.</para>
    
      <screen>
$ svn copy http://svn.example.com/repos/vendor/libcomplex/current  \
           http://svn.example.com/repos/vendor/libcomplex/1.0      \
           -m 'tagging libcomplex-1.0'
&hellip;
$ svn copy http://svn.example.com/repos/vendor/libcomplex/1.0  \
           http://svn.example.com/repos/calc/libcomplex        \
           -m 'bringing libcomplex-1.0 into the main branch'
&hellip;
</screen>

      <para>We check out our project's main branch&mdash;which now
        includes a copy of the first vendor drop&mdash;and we get to
        work customizing the libcomplex code.  Before we know it, our
        modified version of libcomplex is now completely integrated
        into our calculator program.
        <footnote>
          <para>And entirely bug-free, of course!</para>
        </footnote>
      </para>

      <para>A few weeks later, the developers of libcomplex release a
        new version of their library&mdash;version 1.1&mdash;which
        contains some features and functionality that we really want.
        We'd like to upgrade to this new version, but without losing
        the customizations we made to the existing version.  What we
        essentially would like to do is to replace our current
        baseline version of libcomplex 1.0 with a copy of libcomplex
        1.1, and then re-apply the custom modifications we previously
        made to that library to the new version.  But we actually
        approach the problem from the other direction, applying the
        changes made to libcomplex between versions 1.0 and 1.1 to our
        modified copy of it.</para>
      
      <para>To perform this upgrade, we checkout a copy of our vendor
        branch, and replace the code in the
        <filename>current</filename> directory with the new libcomplex
        1.1 source code.  We quite literally copy new files on top of
        existing files, perhaps exploding the libcomplex 1.1 release
        tarball atop our existing files and directories.  The goal
        here is to make our <filename>current</filename> directory
        contain only the libcomplex 1.1 code, and to ensure that all
        that code is under version control.  Oh, and we want to do
        this with as little version control history disturbance as
        possible.</para>

      <para>After replacing the 1.0 code with 1.1 code, <command>svn
        status</command> will show files with local modifications as
        well as, perhaps, some unversioned or missing files.  If we
        did what we were supposed to do, the unversioned files are
        only those new files introduced in the 1.1 release of
        libcomplex&mdash;we run <command>svn add</command> on those to
        get them under version control.  The missing files are files
        that were in 1.0 but not in 1.1, and on those paths we run
        <command>svn remove</command>.  Finally, once our
        <filename>current</filename> working copy contains only the
        libcomplex 1.1 code, we commit the changes we made to get it
        looking that way.</para>

      <para>Our <filename>current</filename> branch now contains the
        new vendor drop.  We tag the new version (in the same way we
        previously tagged the version 1.0 vendor drop), and then merge
        the differences between the tag of the previous version and
        the new current version into our main development
        branch.</para>

      <screen>
$ cd working-copies/calc
$ svn merge http://svn.example.com/repos/vendor/libcomplex/1.0      \
            http://svn.example.com/repos/vendor/libcomplex/current  \
            libcomplex
&hellip; # resolve all the conflicts between their changes and our changes
$ svn commit -m 'merging libcomplex-1.1 into the main branch'
&hellip;
</screen>

      <para>In the trivial use-case, the new version of our
        third-party tool would look, from a files-and-directories
        point of view, just like the previous version.  None of the
        libcomplex source files would have been deleted, renamed or
        moved to different locations&mdash;the new version would
        contain only textual modifications against the previous one.
        In a perfect world, our modifications would apply cleanly to
        the new version of the library, with absolutely no
        complications or conflicts.</para>

     <para>But things aren't always that simple, and in fact it is
       quite common for source files to get moved around between
       releases of software.  This complicates the process of ensuring
       that our modifications are still valid for the new version of
       code, and can quickly degrade into a situation where we have to
       manually recreate our customizations in the new version.  Once
       Subversion knows about the history of a given source
       file&mdash;including all its previous locations&mdash;the
       process of merging in the new version of the library is pretty
       simple.  But we are responsible for telling Subversion how the
       source file layout changed from vendor drop to vendor
       drop.</para>

    </sect2>

    <!-- TODO: Try to clarify some of the steps for svn_load_dirs.pl
         (Garrett sez they've been "glossed over".  Also, consider
         another section on bypassing svn_load_dirs.pl altogether and
         running with just svn merge, now that it ignores ancestry. -->

    <!-- ***************************************************************** -->
    <sect2 id="svn-ch-7-sect-4.2">
      <title><command>svn_load_dirs.pl</command></title>

      <para>Vendor drops that contain more than a few deletes,
        additions and moves complicate the process of upgrading to
        each successive version of the third-party data.  So
        Subversion supplies the <command>svn_load_dirs.pl</command>
        script to assist with this process.  This script automates the
        importing steps we mentioned in the general vendor branch
        management procedure to make sure that mistakes are minimized.
        You will still be responsible for using the merge commands to
        merge the new versions of the third-party data into your main
        development branch, but <command>svn_load_dirs.pl</command>
        can help you more quickly and easily arrive at that
        stage.</para>

      <para>In short, <command>svn_load_dirs.pl</command> is an
        enhancement to <command>svn import</command> that has several
        important characteristics:</para>

      <itemizedlist>
        <listitem>
          <para>It can be run at any point in time to bring an existing
            directory in the repository to exactly match an external
            directory, performing all the necessary adds and deletes,
            and optionally performing moves, too.</para>
        </listitem>
        <listitem>
          <para>It takes care of complicated series of operations between
            which Subversion requires an intermediate commit&mdash;such
            as before renaming a file or directory twice.</para>
        </listitem>
        <listitem>
          <para>It will optionally tag the newly imported directory.</para>
        </listitem>
        <listitem>
          <para>It will optionally add arbitrary properties to files and
            directories that match a regular expression.</para>
        </listitem>
      </itemizedlist>


      <para><command>svn_load_dirs.pl</command> takes three mandatory
        arguments.  The first argument is the URL to the base
        Subversion directory to work in.  This argument is followed by
        the URL&mdash;relative to the first argument&mdash;into which the
        current vendor drop will be imported.  Finally, the third
        argument is the local directory to import.  Using our previous
        example, a typical run of <command>svn_load_dirs.pl</command>
        might look like:</para>

      <screen>
$ svn_load_dirs.pl http://svn.example.com/repos/vendor/libcomplex \
                   current                                        \
                   /path/to/libcomplex-1.1
&hellip;
</screen>

      <para>You can indicate that you'd like
        <command>svn_load_dirs.pl</command> to tag the new vendor drop
        by passing the <option>-t</option> command-line option and
        specifying a tag name.  This tag is another URL relative to
        the first program argument.</para>

      <screen>
$ svn_load_dirs.pl -t libcomplex-1.1                              \
                   http://svn.example.com/repos/vendor/libcomplex \
                   current                                        \
                   /path/to/libcomplex-1.1
&hellip;
</screen>

      <para>When you run <command>svn_load_dirs.pl</command>, it
        examines the contents of your existing <quote>current</quote>
        vendor drop, and compares them with the proposed new vendor
        drop.  In the trivial case, there will be no files that are in
        one version and not the other, and the script will perform the
        new import without incident.  If, however, there are
        discrepancies in the file layouts between versions,
        <command>svn_load_dirs.pl</command> will prompt you for how
        you would like to resolve those differences.  For example, you
        will have the opportunity to tell the script that you know
        that the file <filename>math.c</filename> in version 1.0 of
        libcomplex was renamed to <filename>arithmetic.c</filename> in
        libcomplex 1.1.  Any discrepancies not explained by moves
        are treated as regular additions and deletions.</para>

      <para>The script also accepts a separate configuration file for
        setting properties on files and directories matching a regular
        expression that are <emphasis>added</emphasis> to the
        repository.  This configuration file is specified to
        <command>svn_load_dirs.pl</command> using the
        <option>-p</option> command-line option.  Each line of the
        configuration file is a whitespace-delimited set of two or
        four values: a Perl-style regular expression to match the
        added path against, a control keyword (either
        <literal>break</literal> or <literal>cont</literal>), and then
        optionally a property name and value.</para>

      <screen>
\.png$              break   svn:mime-type   image/png
\.jpe?g$            break   svn:mime-type   image/jpeg
\.m3u$              cont    svn:mime-type   audio/x-mpegurl
\.m3u$              break   svn:eol-style   LF
.*                  break   svn:eol-style   native
</screen>

      <para>For each added path, the configured property changes whose
        regular expression matches the path are applied in order,
        unless the control specification is <literal>break</literal>
        (which means that no more property changes should be applied
        to that path).  If the control specification is
        <literal>cont</literal>&mdash;an abbreviation for
        <literal>continue</literal>&mdash;then matching will continue
        with the next line of the configuration file.</para>

      <para>Any whitespace in the regular expression, property name,
        or property value must be surrounded by either single or
        double quote characters.  You can escape quote characters that
        are not used for wrapping whitespace by preceding them with a
        backslash (<literal>\</literal>) character.  The backslash
        escapes only quotes when parsing the configuration file, so do
        not protect any other characters beyond what is necessary for
        the regular expression.</para>

    </sect2>
  </sect1>

</chapter>

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

Show details Hide details

Change log

r1122 by cmpilato on Feb 25, 2005 Diff

Rename tag to associate with English
version only.

Go to:

Older revisions

r1107 by sussman on Feb 23, 2005 Diff

Create 'book-1.0-final' tag.  This is
a snapshot of the last version
of the book's trunk before we started
documenting 1.1 features.

r658 by sussman on Sep 13, 2004 Diff

Various book improvements, appropriate
for both svn 1.0 and 1.1.

(These changes will be backported to
the 1.0 branch.)
...

r651 by maxb on Sep 04, 2004 Diff

A bunch of minor typographical
corrections from issue 1216.
Thanks to Gareth McCaughan
<Gareth.McCaughan_at_pobox.com>.

...

All revisions of this file

File info

Size: 105781 bytes, 2177 lines

View raw file

File properties

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