ch09-reference.xml - svnbook - Version Control With Subversion

Source path: svn/ tags/ en-1.5-final/ src/ en/ book/ ch09-reference.xml

‹r3305

r4266

<chapter id="svn.ref">
  <title>Subversion Complete Reference</title>
  
  <para>This chapter is intended to be a complete reference to using
    Subversion.  This includes the command-line client
    (<command>svn</command>) and all its subcommands, as well as the
    repository administration programs (<command>svnadmin</command>
    and <command>svnlook</command>) and their respective
    subcommands.</para>

  
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.ref.svn">
    <title>The Subversion Command-Line Client: <command>svn</command></title>
    
    <para>To use the command-line client, type
      <command>svn</command>, the subcommand you wish to use,
      <footnote>
        <para>Well, you don't need a subcommand to use the
          <option>--version</option> option, but we'll get to that in
          just a minute.</para>
      </footnote>
      and any options or targets that you wish to operate on&mdash;the
      subcommand and the options need not appear in a specific order.
      For example, all of the following are valid ways to
      use <command>svn status</command>:</para>

    <screen>
$ svn -v status
$ svn status -v 
$ svn status -v myfile
</screen>

    <para>You can find many more examples of how to use most client
      commands in <xref linkend="svn.tour"/> and commands for managing
      properties in <xref linkend="svn.advanced.props"/>.</para>
    
    <!-- =============================================================== -->
    <sect2 id="svn.ref.svn.sw">
      <title>svn Options</title> 
      
      <para>While Subversion has different options for its
        subcommands, all options exist in a single
        namespace&mdash;that is, each option is guaranteed to mean the
        same thing regardless of the subcommand you use it with.  For
        example, <option>--verbose</option> (<option>-v</option>)
        always means <quote>verbose output,</quote> regardless of the
        subcommand you use it with.</para>

      <para>The <command>svn</command> command-line client usually
        exits quickly with an error if you pass it an option which
        does not apply to the specified subcommand.  But as of
        Subversion 1.5, several of the options which apply to
        all&mdash;or nearly all&mdash;of the subcommands have been
        deemed acceptable by all subcommands, even if they have no
        effect on some of them.  They appear grouped together in the
        command-line client's usage messages as global options.  This
        was done to assist folks who write scripts which wrap the
        command-line client.  These global options are as
        follows:</para>
        
      <variablelist>

        <varlistentry>
          <term><option>--config-dir</option>
            <replaceable>DIR</replaceable></term>
          <listitem>
            <para>Instructs Subversion to read configuration
              information from the specified directory instead of the
              default location (<filename>.subversion</filename> in
              the user's home directory).</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--no-auth-cache</option></term>
          <listitem>
            <para>Prevents caching of authentication information
              (e.g., username and password) in the Subversion
              runtime configuration directories.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--non-interactive</option></term>
          <listitem>
            <para>Disables all interactive prompting.  Some examples
              of interactive prompting include requests for
              authentication credentials and conflict resolution
              decisions.  This is useful if you're running Subversion
              inside an automated script and it's more appropriate
              to have Subversion fail than to prompt for more
              information.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--password</option>
            <replaceable>PASSWD</replaceable></term>
          <listitem>
            <para>Specifies the password to use when authenticating
              against a Subversion server.  If not provided, or if
              incorrect, Subversion will prompt you for this
              information as needed.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--username</option>
            <replaceable>NAME</replaceable></term>
          <listitem>
            <para>Specifies the username to use when authenticating
              against a Subversion server.  If not provided, or if
              incorrect, Subversion will prompt you for this
              information as needed.</para>
          </listitem>
        </varlistentry>
        
      </variablelist>

      <para>The rest of the options apply and are accepted by only a
        subset of the subcommand.  They are as follows:</para>

      <variablelist>
        
        <varlistentry>
          <term><option>--accept</option>
            <replaceable>ACTION</replaceable></term>
          <listitem>
            <para>Specifies an action for automatic conflict resolution.
              Possible actions are <literal>postpone</literal>,
              <literal>base</literal>, <literal>mine-full</literal>,
              <literal>theirs-full</literal>, <literal>edit</literal>, and
              <literal>launch</literal>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--auto-props</option></term>
          <listitem>
            <para>Enables auto-props, overriding the
              <literal>enable-auto-props</literal> directive in the
              <filename>config</filename> file.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--change</option> (<option>-c</option>)
            <replaceable>ARG</replaceable></term>
          <listitem>
            <para>Used as a means to refer to a specific
              <quote>change</quote> (a.k.a. a revision).  This option is
              syntactic sugar for <quote>-r ARG-1:ARG</quote>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--changelist</option>
            <replaceable>ARG</replaceable></term>
          <listitem>
            <para>Instructs Subversion to operate only on members of the changelist named
              <replaceable>ARG</replaceable>.  You can use this option
              multiple times to specify sets of changelists.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--cl</option>
            <replaceable>ARG</replaceable></term>
          <listitem>
            <para>An alias for the
              <option>--changelist</option> option.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--depth</option>
            <replaceable>ARG</replaceable></term>
          <listitem>
            <para>Instructs Subversion to limit the scope of an operation to a particular tree
              depth.  <replaceable>ARG</replaceable> is one of
              <literal>empty</literal>, <literal>files</literal>,
              <literal>immediates</literal>, or
              <literal>infinity</literal>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--diff-cmd</option>
            <replaceable>CMD</replaceable></term>
          <listitem>
            <para>Specifies an external program to use to show
              differences between files.  When <command>svn
              diff</command> is invoked without this option, it uses
              Subversion's internal diff engine, which provides
              unified diffs by default.  If you want to use an
              external diff program, use <option>--diff-cmd</option>.
              You can pass options to the diff program with the
              <option>--extensions</option> option (more on that later
              in this section).</para>
          </listitem>
        </varlistentry>
      
        <varlistentry>
          <term><option>--diff3-cmd</option>
            <replaceable>CMD</replaceable></term>
          <listitem>
            <para>Specifies an external program to use to merge files.</para>
          </listitem>
        </varlistentry>
      
        <varlistentry>
          <term><option>--dry-run</option></term>
          <listitem>
            <para>Goes through all the motions of running a command,
              but makes no actual changes&mdash;either on disk or in
              the repository.</para>
          </listitem>
        </varlistentry>
      
        <varlistentry>
          <term><option>--editor-cmd</option>
            <replaceable>CMD</replaceable></term>
          <listitem>
            <para>Specifies an external program to use to edit a log message
              or a property value.  See the <literal>editor-cmd</literal>
              section in <xref linkend="svn.advanced.confarea.opts.config"/>
              for ways to specify a default editor.</para>
          </listitem>
        </varlistentry>
      
        <varlistentry>
          <term><option>--encoding</option> <replaceable>ENC</replaceable></term>
          <listitem>
            <para>Tells Subversion that your commit message is encoded
              in the charset provided.  The default is your operating
              system's native locale, and you should specify the
              encoding if your commit message is in any other
              encoding.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--extensions</option> (<option>-x</option>)
          <replaceable>ARGS</replaceable></term>
          <listitem>
            <para>Specifies an argument or arguments that Subversion
              should pass to an external diff command.  This option is
              valid only when used with the <command>svn
              diff</command> or <command>svn merge</command> commands,
              with the
              <option>--diff-cmd</option> option.
              If you wish to pass multiple
              arguments, you must enclose all of them in quotes (e.g.,
              <userinput>svn diff --diff-cmd /usr/bin/diff -x
              "-b -E"</userinput>).</para>
          </listitem>

          <!-- TODO(fitz): Document -u -b -w and - -ignore-eol-style -->

        </varlistentry>
      
        <varlistentry>
          <term><option>--file</option> (<option>-F</option>)
            <replaceable>FILENAME</replaceable>
          </term>
          <listitem>
            <para>Uses the contents of the named file for the
              specified subcommand, though different subcommands do
              different things with this content.  For example,
              <command>svn commit</command> uses the content as a
              commit log, whereas <command>svn propset</command> uses
              it as a property value.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--force</option></term>
          <listitem>
            <para>Forces a particular command or operation to run.
              Subversion will prevent you from performing some operations
              in normal usage, but you can pass the
              force option to tell Subversion <quote>I know what I'm
              doing as well as the possible repercussions of doing it,
              so let me at 'em.</quote>  This option is the
              programmatic equivalent of doing your own electrical
              work with the power on&mdash;if you don't know what
              you're doing, you're likely to get a nasty shock.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--force-log</option></term>
          <listitem>
            <para>Forces a suspicious parameter passed to the
              <option>--message</option> (<option>-m</option>) or
              <option>--file</option> (<option>-F</option>) option to
              be accepted as valid.  By default, Subversion will
              produce an error if parameters to these options look
              like they might instead be targets of the subcommand.
              For example, if you pass a versioned file's path to the
              <option>--file</option> (<option>-F</option>) option,
              Subversion will assume you've made a mistake, that the
              path was instead intended as the target of the
              operation, and that you simply failed to provide some
              other&mdash;unversioned&mdash;file as the source of your
              log message.  To assert your intent and override these
              types of errors, pass the <option>--force-log</option>
              option to subcommands that accept log messages.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--help</option> (<option>-h</option>) or
                <option>-?</option>)
          </term>
          <listitem>
            <para>If used with one or more subcommands, shows the
              built-in help text for each.  If used alone, it displays
              the general client help text.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--ignore-ancestry</option></term>
          <listitem>
            <para>Tells Subversion to ignore ancestry when calculating
              differences (rely on path contents alone).</para>
          </listitem>
        </varlistentry>
      
        <varlistentry>
          <term><option>--ignore-externals</option></term>
          <listitem>
            <para>Tells Subversion to ignore externals definitions and
              the external working copies managed by them.</para>
          </listitem>
        </varlistentry>
      
        <varlistentry>
          <term><option>--incremental</option></term>
          <listitem>
            <para>Prints output in a format suitable for
              concatenation.</para>
          </listitem>
        </varlistentry>
      
        <varlistentry>
          <term><option>--keep-changelists</option></term>
          <listitem>
            <para>Tells Subversion not to delete changelists after committing.</para>
          </listitem>
        </varlistentry>
      
        <varlistentry>
          <term><option>--keep-local</option></term>
          <listitem>
            <para>Keeps the local copy of a file or directory (used
              with the <command>svn delete</command> command).</para>
          </listitem>
        </varlistentry>
      
        <varlistentry>
          <term><option>--limit</option> (<option>-l</option>)
            <replaceable>NUM</replaceable></term>
          <listitem>
            <para>Shows only the first <replaceable>NUM</replaceable>
              log messages.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--message</option> (<option>-m</option>)
            <replaceable>MESSAGE</replaceable>
          </term>
          <listitem>
            <para>Indicates that you will specify either a log message
              or a lock comment on the command line, following this
              option.  For example:</para>
            
            <screen>
$ svn commit -m "They don't make Sunday."
</screen>
          </listitem>
        </varlistentry>
      
        <varlistentry>
          <term><option>--new</option> <replaceable>ARG</replaceable></term>
          <listitem>
            <para>Uses <replaceable>ARG</replaceable> as the newer
              target (for use with <command>svn diff</command>).</para>
          </listitem>
        </varlistentry>
      
        <varlistentry>
          <term><option>--no-auto-props</option></term>
          <listitem>
            <para>Disables auto-props, overriding the
              <literal>enable-auto-props</literal> directive in the
              <filename>config</filename> file.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--no-diff-deleted</option></term>
        <listitem>
            <para>Prevents Subversion from printing differences for
              deleted files.  The default behavior when you remove a
              file is for <command>svn diff</command> to print the
              same differences that you would see if you had left
              the file but removed all the content.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--no-ignore</option></term>
          <listitem>
            <para>Shows files in the status listing that would
              normally be omitted since they match a pattern in the
              <literal>global-ignores</literal> configuration option
              or the <literal>svn:ignore</literal> property.  See <xref
              linkend="svn.advanced.confarea.opts.config"/> and <xref
              linkend="svn.advanced.props.special.ignore"/> for more
              information.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--no-unlock</option></term>
          <listitem>
            <para>Tells Subversion not to automatically unlock files (the default commit
              behavior is to unlock all files listed as part of the
              commit).  See <xref linkend="svn.advanced.locking"/> for
              more information.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--non-recursive</option> (<option>-N</option>)</term>
          <listitem>
            <para><emphasis>Deprecated</emphasis>.  Stops a subcommand
              from recursing into subdirectories.  Most subcommands
              recurse by default, but some subcommands&mdash;usually
              those that have the potential to remove or undo your
              local modifications&mdash;do not.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--notice-ancestry</option></term>
          <listitem>
            <para>Pays attention to ancestry when calculating 
              differences.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--old</option> <replaceable>ARG</replaceable></term>
          <listitem>
            <para>Uses <replaceable>ARG</replaceable> as the older
              target (for use with <command>svn diff</command>).</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--parents</option></term>
          <listitem>
            <para>Creates and adds nonexistent or nonversioned parent
              subdirectories to the working copy or repository as part
              of an operation.  This is useful for automatically
              creating multiple subdirectories where none currently
              exist.  If performed on a URL, all the directories will
              be created in a single commit.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--quiet</option> (<option>-q</option>)</term>
          <listitem>
            <para>Requests that the client print only essential
              information while performing an operation.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--record-only</option></term>
          <listitem>
            <para>Marks revisions as merged (for use with
              <option>--revision</option>).</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--recursive</option> (<option>-R</option>)</term>
          <listitem>
            <para>Makes a subcommand recurse into subdirectories.
              Most subcommands recurse by default.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--reintegrate</option></term>
          <listitem>
            <para>Used with the <command>svn merge</command>
              subcommand, merges all of the source URL's changes into
              the working copy.  See
              <xref linkend="svn.branchemerge.basicmerging.stayinsync"/>
              for details.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--relocate</option> <replaceable>FROM TO
          [PATH...]</replaceable></term>
          <listitem>
            <para>Used with the <command>svn switch</command>
              subcommand, changes the location of the repository that
              your working copy references.  This is useful if the
              location of your repository changes and you have an
              existing working copy that you'd like to continue to
              use.  See <command>svn switch</command> for an
              example.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--remove</option>
            <replaceable>ARG</replaceable></term>
          <listitem>
            <para>Disassociates <replaceable>ARG</replaceable> from a
              changelist</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--revision</option> (<option>-r</option>)
            <replaceable>REV</replaceable>
          </term>
          <listitem>
            <para>Indicates that you're going to supply a revision (or
              range of revisions) for a particular operation.  You can
              provide revision numbers, keywords, or dates (in
              curly braces) as arguments to the revision option.  If
              you wish to offer a range of revisions, you can
              provide two revisions separated by a colon.  For
              example:</para>

            <screen>
$ svn log -r 1729
$ svn log -r 1729:HEAD
$ svn log -r 1729:1744
$ svn log -r {2001-12-04}:{2002-02-17}
$ svn log -r 1729:{2002-02-17}
</screen>

            <para>See <xref linkend="svn.tour.revs.keywords"/> for more
              information.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--revprop</option></term>
          <listitem>
            <para>Operates on a revision property instead of a
              property specific to a file or directory.  This option
              requires that you also pass a revision with the
              <option>--revision</option> (<option>-r</option>)
              option.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--set-depth</option>
            <replaceable>ARG</replaceable></term>
          <listitem>
            <para>Sets the sticky depth on a directory in a working
              copy to one of <literal>empty</literal>,
              <literal>files</literal>, <literal>immediates</literal>,
              or <literal>infinity</literal>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--show-revs</option> <replaceable>ARG</replaceable></term>
          <listitem>
            <para>Used to make <command>svn mergeinfo</command>
              display either <literal>merged</literal>
              or <literal>eligible</literal> revisions.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--show-updates</option> (<option>-u</option>)</term>
          <listitem>
            <para>Causes the client to display information about
              which files in your working copy are out of date.
              This doesn't actually update any of your
              files&mdash;it just shows you which files will be
              updated if you then use <command>svn update</command>.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--stop-on-copy</option></term>
          <listitem>
            <para>Causes a Subversion subcommand that traverses
              the history of a versioned resource to stop harvesting
              that historical information when a copy&mdash;that is, a
              location in history where that resource was copied from
              another location in the repository&mdash;is
              encountered.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--strict</option></term>
          <listitem>
            <para>Causes Subversion to use strict semantics, a notion
              that is rather vague unless talking about specific
              subcommands (namely, <command>svn propget</command>).</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--targets</option>
            <replaceable>FILENAME</replaceable></term>
          <listitem>
            <para>Tells Subversion to get the list of files that you
              wish to operate on from the filename that you provide
              instead of listing all the files on the command line.
            </para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--use-merge-history</option>
            (<option>-g</option>)</term>
          <listitem>
            <para>Uses or displays additional information from merge
              history.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--verbose</option> (<option>-v</option>)</term>
          <listitem>
            <para>Requests that the client print out as much
              information as it can while running any subcommand.
              This may result in Subversion printing out additional
              fields, detailed information about every file, or
              additional information regarding its actions.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--version</option></term>
          <listitem>
            <para>Prints the client version info.  This information
              includes not only the version number of the client, but
              also a listing of all repository access modules that the
              client can use to access a Subversion repository.
              With <option>--quiet</option> (<option>-q</option>) it
              prints only the version number in a compact form.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--with-all-revprops</option></term>
          <listitem>
            <para>Used with the <option>--xml</option> option to <command>svn log</command>,
            will retrieve and display all revision
            properties in the log output.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--with-revprop</option>
            <replaceable>ARG</replaceable></term>
          <listitem>
            <para>When used with any command that writes to the
              repository, sets the revision property, using the
              <replaceable>NAME=VALUE</replaceable> format,
              <replaceable>NAME</replaceable> to
              <replaceable>VALUE</replaceable>.  When used with
              <command>svn log</command> in <option>--xml</option> mode, this displays the value of
              <replaceable>ARG</replaceable> in the log output.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--xml</option></term>
          <listitem>
            <para>Prints output in XML format.</para>
          </listitem>
        </varlistentry>
        
      </variablelist>
      
    </sect2>
    
    <!-- =============================================================== -->
    <sect2 id="svn.ref.svn.c">
      <title>svn Subcommands</title>

      <para>Here are the various subcommands for the <command>svn</command> program.  For the sake of
        brevity, we omit the global options (described in <xref
        linkend="svn.ref.svn.sw" />) from the subcommand descriptions
        which follow.</para>

      <refentry id="svn.ref.svn.c.add">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>add</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn add</refname>
          <refpurpose>Add files, directories, or symbolic links.</refpurpose>
        </refnamediv>

        <refsect1>
          <title>Synopsis</title> 
          <programlisting>svn add PATH...</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>
          
          <para>Schedule files, directories, or symbolic links in your
            working copy for addition to the repository.  They will be
            uploaded and added to the repository on your next commit.
            If you add something and change your mind before
            committing, you can unschedule the addition using
            <command>svn revert</command>.
          </para>
        </refsect1>
        
        <refsect1>
          <title>Alternate names</title>
          <para>None</para>
        </refsect1>
        
        <refsect1>
          <title>Changes</title>
          <para>Working copy</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>No</para>
        </refsect1>
        
        <refsect1>
          <title>Options</title>

          <screen>
--auto-props
--depth ARG
--force
--no-auto-props
--no-ignore
--parents
--quiet (-q)
--targets FILENAME
</screen>
        </refsect1>
        
        <refsect1>
          <title>Examples</title>
          
          <para>To add a file to your working copy:</para>

          <screen>
$ svn add foo.c 
A         foo.c
</screen>

          <para>When adding a directory, the default behavior of
            <command>svn add</command> is to recurse:</para>
          
          <screen>
$ svn add testdir
A         testdir
A         testdir/a
A         testdir/b
A         testdir/c
A         testdir/d
</screen>

          <para>You can add a directory without adding its
            contents:</para>
          
          <screen>
$ svn add --depth=empty otherdir
A         otherdir
</screen>

          <para>Normally, the command <userinput>svn add *</userinput>
            will skip over any directories that are already under
            version control.  Sometimes, however, you may want to add
            every unversioned object in your working copy, including
            those hiding deeper.  Passing the
            <option>--force</option> option makes <command>svn
            add</command> recurse into versioned directories:
          </para>

          <screen>
$ svn add * --force
A         foo.c
A         somedir/bar.c
A  (bin)  otherdir/docs/baz.doc
&hellip;
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.blame">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>blame</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn blame</refname>
          <refpurpose>Show author and revision information inline
            for the specified files or URLs.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn blame TARGET[@REV]...</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>
          
          <para>Show author and revision information inline for the
            specified files or URLs.  Each line of text is annotated
            at the beginning with the author (username) and the
            revision number for the last change to that line.</para>
        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para><command>praise</command>, <command>annotate</command>, <command>ann</command></para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Nothing</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Yes</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--extensions (-x) ARG
--force
--incremental
--revision (-r) ARG
--use-merge-history (-g)
--verbose (-v)
--xml
</screen>

<!--

TODO(fitz): doc this:
  - -incremental            : give output suitable for concatenation
  - -xml                    : output in XML
  -x [- -extensions] arg    : Default: '-u'. When Subversion is invoking an
                             external diff program, ARG is simply passed along
                             to the program. But when Subversion is using its
                             default internal diff implementation, or when
                             Subversion is displaying blame annotations, ARG
                             could be any of the following:
                                -u (- -unified):
                                   Output 3 lines of unified context.
                                -b (- -ignore-space-change):
                                   Ignore changes in the amount of white space.
                                -w (- -ignore-all-space):
                                   Ignore all white space.
                                - -ignore-eol-style:
                                   Ignore changes in EOL style
  - -force                  : force operation to run

-->





        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>If you want to see blame-annotated source for
            <filename>readme.txt</filename> in your test
            repository:</para>
          <screen>
$ svn blame http://svn.red-bean.com/repos/test/readme.txt
     3      sally This is a README file.
     5      harry You should read this.
</screen>

          <para>Even if <command>svn blame</command> says that Harry
            last modified <filename>readme.txt</filename> in revision
            5, you'll have to examine exactly what the revision
            changed to be sure that Harry changed
            the <emphasis>context</emphasis> of the line&mdash;he may
            have adjusted just the whitespace.
          </para>

          <para>If you use the <option>--xml</option> option, you can
            get XML output describing the blame annotations, but not
            the contents of the lines themselves:</para>

          <screen>
$ svn blame --xml http://svn.red-bean.com/repos/test/readme.txt
&lt;?xml version="1.0"?&gt;
&lt;blame&gt;
&lt;target
   path="sandwich.txt"&gt;
&lt;entry
   line-number="1"&gt;
&lt;commit
   revision="3"&gt;
&lt;author&gt;sally&lt;/author&gt;
&lt;date&gt;2008-05-25T19:12:31.428953Z&lt;/date&gt;
&lt;/commit&gt;
&lt;/entry&gt;
&lt;entry
   line-number="2"&gt;
&lt;commit
   revision="5"&gt;
&lt;author&gt;harry&lt;/author&gt;
&lt;date&gt;2008-05-29T03:26:12.293121Z&lt;/date&gt;
&lt;/commit&gt;
&lt;/entry&gt;
&lt;/target&gt;
&lt;/blame&gt;
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.cat">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>cat</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn cat</refname>
          <refpurpose>Output the contents of the specified files or
            URLs.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn cat TARGET[@REV]...</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>
          
          <para>Output the contents of the specified files or URLs.
            For listing the contents of directories, see <command>svn
            list</command> later in this chapter.</para>
        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para>None</para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Nothing</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Yes</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--revision (-r) REV
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>If you want to view <filename>readme.txt</filename> in
            your repository without checking it out:</para>
          <screen>
$ svn cat http://svn.red-bean.com/repos/test/readme.txt
This is a README file.
You should read this.
</screen>

          <tip>
            <para>If your working copy is out of date (or you have
              local modifications) and you want to see the
              <literal>HEAD</literal> revision of a file in your
              working copy, <command>svn cat -r HEAD <replaceable>FILENAME</replaceable></command> will
              automatically fetch the <literal>HEAD</literal> revision
              of the specified path:</para>
          </tip>

          <screen>
$ cat foo.c
This file is in my local working copy 
and has changes that I've made.

$ svn cat -r HEAD foo.c
Latest revision fresh from the repository!
</screen>
          
        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.changelist">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>changelist</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn changelist</refname>
          <refpurpose>Associate (or deassociate) local paths with a
            changelist.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>changelist CLNAME TARGET...</programlisting>
          <programlisting>changelist --remove TARGET...</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>
          
          <para>Used for dividing files in a working copy into a
            changelist (logical named grouping) in order to allow
            users to easily work on multiple file collections within a
            single working copy.</para>

        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para><command>cl</command></para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Working copy</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>No</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--changelist ARG
--depth ARG
--quiet (-q)
--recursive (-R)
--remove
--targets ARG
</screen>
        </refsect1>

        <refsect1>
          <title>Example</title>

          <para>Edit three files, add them to a changelist, then
            commit only files in that changelist:</para>

          <screen>
$ svn cl issue1729 foo.c bar.c baz.c
Path 'foo.c' is now a member of changelist 'issue1729'.
Path 'bar.c' is now a member of changelist 'issue1729'.
Path 'baz.c' is now a member of changelist 'issue1729'.

$ svn status
A      someotherfile.c
A      test/sometest.c

--- Changelist 'issue1729':
A      foo.c
A      bar.c
A      baz.c

$ svn commit --changelist issue1729 -m "Fixing Issue 1729."
Adding         bar.c
Adding         baz.c
Adding         foo.c
Transmitting file data ...
Committed revision 2.

$ svn status
A      someotherfile.c
A      test/sometest.c
</screen>

          <para>Note that only the files in changelist
            <replaceable>issue1729</replaceable> were
            committed.</para>
          
        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.checkout">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>checkout</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn checkout</refname>
          <refpurpose>Check out a working copy from a repository.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn checkout URL[@REV]... [PATH]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>
          
          <para>Check out a working copy from a repository.  If
            <replaceable>PATH</replaceable> is omitted, the
            basename of the URL will be used as the destination.
            If multiple URLs are given, each will be checked out into a
            subdirectory of <replaceable>PATH</replaceable>, with the
            name of the subdirectory being the basename of the
            URL.</para>

        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para><command>co</command></para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Creates a working copy</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Yes</para>
        </refsect1>

        <refsect1>
          <title>Options</title>
          
          <screen>
--depth ARG
--force
--ignore-externals
--quiet (-q)
--revision (-r) REV
</screen>
        </refsect1>
        
        <refsect1>
          <title>Examples</title>

          <para>Check out a working copy into a directory called
            <filename>mine</filename>:</para>

          <screen>
$ svn checkout file:///var/svn/repos/test mine
A  mine/a
A  mine/b
A  mine/c
A  mine/d
Checked out revision 20.
$ ls
mine
</screen>

          <para>Check out two different directories into two separate
            working copies:</para>

          <screen>
$ svn checkout file:///var/svn/repos/test  file:///var/svn/repos/quiz
A  test/a
A  test/b
A  test/c
A  test/d
Checked out revision 20.
A  quiz/l
A  quiz/m
Checked out revision 13.
$ ls
quiz  test
</screen>

          <para>Check out two different directories into two separate
            working copies, but place both into a directory called
            <filename>working-copies</filename>:</para>

          <screen>
$ svn checkout file:///var/svn/repos/test  file:///var/svn/repos/quiz working-copies
A  working-copies/test/a
A  working-copies/test/b
A  working-copies/test/c
A  working-copies/test/d
Checked out revision 20.
A  working-copies/quiz/l
A  working-copies/quiz/m
Checked out revision 13.
$ ls
working-copies
</screen>

          <para>If you interrupt a checkout (or something else
            interrupts your checkout, such as loss of connectivity,
            etc.), you can restart it either by issuing the identical
            checkout command again or by updating the incomplete
            working copy:</para>

          <screen>
$ svn checkout file:///var/svn/repos/test mine
A  mine/a
A  mine/b
^C
svn: The operation was interrupted
svn: caught SIGINT

$ svn checkout file:///var/svn/repos/test mine
A  mine/c
^C
svn: The operation was interrupted
svn: caught SIGINT

$ svn update mine
A  mine/d
Updated to revision 20.
</screen>

          <para>If you wish to check out some revision other than the
            most recent one, you can do so by providing the
            <option>--revision</option> (<option>-r</option>) option
            to the <command>svn checkout</command> command:</para>

          <screen>
$ svn checkout -r 2 file:///var/svn/repos/test mine
A  mine/a
Checked out revision 2.
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.cleanup">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>cleanup</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn cleanup</refname>
          <refpurpose>Recursively clean up the working copy</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn cleanup [PATH...]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Recursively clean up the working copy, removing
            working copy locks and resuming unfinished operations.  If
            you ever get a <literal>working copy locked</literal>
            error, run this command to remove stale locks and get your
            working copy into a usable state again.</para>

          <para>If, for some reason, an <command>svn update</command>
            fails due to a problem running an external diff program
            (e.g., user input or network failure), pass the
            <option>--diff3-cmd</option> to allow cleanup to complete
            any merging with your external diff program.  You can also
            specify any configuration directory with the
            <option>--config-dir</option> option, but you should need
            these options extremely infrequently.</para>

        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para>None</para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Working copy</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>No</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--diff3-cmd CMD
</screen>

        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>Well, there's not much to the examples here, as
            <command>svn cleanup</command> generates no output.  If
            you pass no <replaceable>PATH</replaceable>, then
            <quote><filename>.</filename></quote> is used:</para>

          <screen>
$ svn cleanup

$ svn cleanup /var/svn/working-copy
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.commit">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>commit</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn commit</refname>
          <refpurpose>Send changes from your working copy to the repository.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn commit [PATH...]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Send changes from your working copy to the
            repository.  If you do not supply a log message with your
            commit by using either the <option>--file</option> or
            <option>--message</option> option,
            <command>svn</command> will launch your editor for you
            to compose a commit message.  See the
            <literal>editor-cmd</literal> list entry in <xref
            linkend="svn.advanced.confarea.opts.config"/>.</para>

          <para><command>svn commit</command> will send any lock
            tokens that it finds and will release locks on all
            <replaceable>PATH</replaceable>s committed (recursively)
            unless <option>--no-unlock</option> is passed.</para>

          <tip>
            <para>If you begin a commit and Subversion launches your
              editor to compose the commit message, you can still
              abort without committing your changes.  If you want to
              cancel your commit, just quit your editor without saving
              your commit message and Subversion will prompt you to
              either abort the commit, continue with no message, or
              edit the message again.</para>
          </tip>

        </refsect1>


        
        <refsect1>
          <title>Alternate names</title>
          <para><command>ci</command> (short for <quote>check in</quote>; not 
            <command>co</command>, which is an alias for the 
            <command>checkout</command> subcommand)</para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Working copy; repository</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Yes</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--changelist ARG
--depth ARG
--editor-cmd ARG
--encoding ENC
--file (-F) FILE
--force-log
--keep-changelists
--message (-m) TEXT
--no-unlock
--quiet (-q)
--targets FILENAME
--with-revprop ARG
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>Commit a simple modification to a file with the
            commit message on the command line and an implicit
            target of your current directory
            (<quote><filename>.</filename></quote>):</para>
          
          <screen>
$ svn commit -m "added howto section."
Sending        a
Transmitting file data .
Committed revision 3.
</screen>

          <para>Commit a modification to the file
            <filename>foo.c</filename> (explicitly specified on the
            command line) with the commit message in a file named
            <filename>msg</filename>:</para>

          <screen>
$ svn commit -F msg foo.c
Sending        foo.c
Transmitting file data .
Committed revision 5.
</screen>

          <para>If you want to use a file that's under version
            control for your commit message with
            <option>--file</option>, you need to pass the
            <option>--force-log</option> option:</para>

          <screen>
$ svn commit --file file_under_vc.txt foo.c
svn: The log message file is under version control
svn: Log message file is a versioned file; use '--force-log' to override

$ svn commit --force-log --file file_under_vc.txt foo.c
Sending        foo.c
Transmitting file data .
Committed revision 6.
</screen>

          <para>To commit a file scheduled for deletion:</para>

          <screen>
$ svn commit -m "removed file 'c'."
Deleting       c

Committed revision 7.
</screen>
          
        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.copy">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>copy</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn copy</refname>
          <refpurpose>Copy a file or directory in a working copy or
            in the repository.</refpurpose>
        </refnamediv>

        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn copy SRC[@REV]... DST</programlisting>
        </refsect1>

        <refsect1>
          <title>Description</title>
          
          <para>Copy one or more files in a working copy or in the
            repository.  When copying multiple sources, they will be
            added as children of <replaceable>DST</replaceable>, which must be a directory.
            <replaceable>SRC</replaceable> and
            <replaceable>DST</replaceable> can each be either a
            working copy (WC) path or URL:</para>
            
            <variablelist>

              <varlistentry>
                <term>WC &rarr; WC</term>
                <listitem>
                  <para>Copy and schedule an item for
                    addition (with history).</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>WC &rarr; URL</term>
                <listitem>
                  <para>Immediately commit a copy of WC to URL.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>URL &rarr; WC</term>
                <listitem>
                  <para>Check out URL into WC and schedule it for
                    addition.</para>
                </listitem>
              </varlistentry>

              <varlistentry>
                <term>URL &rarr; URL</term>
                <listitem>
                  <para>Complete server-side copy.  This is
                    usually used to branch and tag.</para>
                </listitem>
              </varlistentry>

            </variablelist>

          <para>When copying multiple sources, they will be added as
            children of <replaceable>DST</replaceable>, which must be
            a directory.</para>

          <para>If no peg revision (i.e.,
            <replaceable>@REV</replaceable>) is supplied, by default
            the <literal>BASE</literal> revision will be used for
            files copied from the working copy, while the
            <literal>HEAD</literal> revision will be used for files
            copied from a URL.</para>

          <note>
            <para>You can only copy files within a single repository.
              Subversion does not support cross-repository copying.</para>
          </note>

        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para><command>cp</command></para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Repository if destination is a URL; working copy if destination is a WC path</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Yes, if source or destination is in the repository, or if needed
            to look up the source revision number.</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--editor-cmd EDITOR
--encoding ENC
--file (-F) FILE
--force-log
--message (-m) TEXT
--parents
--quiet (-q)
--revision (-r) REV
--with-revprop ARG
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>Copy an item within your working copy (this
            schedules the copy&mdash;nothing goes into the repository
            until you commit):</para>

          <screen>
$ svn copy foo.txt bar.txt
A         bar.txt
$ svn status
A  +   bar.txt
</screen>

          <para>Copy several files in a working copy into a
            subdirectory:</para>

          <screen>
$ svn cp bat.c baz.c qux.c src
A         src/bat.c
A         src/baz.c
A         src/qux.c
</screen>

          <para>Copy revision 8 of <filename>bat.c</filename> into your
            working copy under a different name:</para>

          <screen>
$ svn cp -r 8 bat.c ya-old-bat.c
A         ya-old-bat.c
</screen>

          <para>Copy an item in your working copy to a URL in the
            repository (this is an immediate commit, so you must supply a
            commit message):</para>

          <screen>
$ svn copy near.txt file:///var/svn/repos/test/far-away.txt -m "Remote copy."

Committed revision 8.
</screen>

          <para>Copy an item from the repository to your working
            copy (this just schedules the copy&mdash;nothing goes into the
            repository until you commit):</para>
 
          <screen>
$ svn copy file:///var/svn/repos/test/far-away -r 6 near-here
A         near-here
</screen>

          <tip>
            <para>This is the recommended way to resurrect a dead
              file in your repository!</para>
          </tip>

          <para>And finally, copy between two URLs:</para>

          <screen>
$ svn copy file:///var/svn/repos/test/far-away \
           file:///var/svn/repos/test/over-there -m "remote copy."

Committed revision 9.
</screen>

          <screen>
$ svn copy file:///var/svn/repos/test/trunk \
           file:///var/svn/repos/test/tags/0.6.32-prerelease -m "tag tree"

Committed revision 12.
</screen>

          <tip>
            <para>This is the easiest way to <quote>tag</quote> a
              revision in your repository&mdash;just <command>svn
              copy</command> that revision (usually
              <literal>HEAD</literal>) into your <filename>tags</filename> directory.</para>
          </tip>

          <para>And don't worry if you forgot to tag&mdash;you can
            always specify an older revision and tag anytime:</para>

          <screen>
$ svn copy -r 11 file:///var/svn/repos/test/trunk \
           file:///var/svn/repos/test/tags/0.6.32-prerelease \
           -m "Forgot to tag at rev 11"

Committed revision 13.
</screen>
        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.delete">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>delete</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn delete</refname>
          <refpurpose>Delete an item from a working copy
            or the repository.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn delete PATH...</programlisting>
          <programlisting>svn delete URL...</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Items specified by <replaceable>PATH</replaceable> are
            scheduled for deletion upon the next commit.  Files (and
            directories that have not been committed) are immediately
            removed from the working copy unless the
            <option>--keep-local</option> option is given.  The
            command will not remove any unversioned or modified items;
            use the <option>--force</option> option to override this
            behavior.</para>

          <para>Items specified by URL are deleted from
            the repository via an immediate commit.  Multiple URLs are
            committed atomically.</para>
        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para><command>del</command>, <command>remove</command>, <command>rm</command></para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Working copy if operating on files; repository if
            operating on URLs</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Only if operating on URLs</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--editor-cmd EDITOR
--encoding ENC
--file (-F) FILE
--force
--force-log
--keep-local
--message (-m) TEXT
--quiet (-q)
--targets FILENAME
--with-revprop ARG
</screen>
        </refsect1>
        
        <refsect1>
          <title>Examples</title>

          <para>Using <command>svn</command> to delete a file from
            your working copy deletes your local copy of the file, but
            it merely schedules the file to be deleted from the
            repository.  When you commit, the file is deleted in the
            repository.</para>

          <screen>
$ svn delete myfile
D         myfile

$ svn commit -m "Deleted file 'myfile'."
Deleting       myfile
Transmitting file data .
Committed revision 14.
</screen>

          <para>Deleting a URL, however, is immediate, so you have
            to supply a log message:</para>

          <screen>
$ svn delete -m "Deleting file 'yourfile'" \
             file:///var/svn/repos/test/yourfile

Committed revision 15.
</screen>

          <para>Here's an example of how to force deletion of a file
            that has local mods:</para>

          <screen>
$ svn delete over-there 
svn: Attempting restricted operation for modified resource
svn: Use --force to override this restriction
svn: 'over-there' has local modifications

$ svn delete --force over-there 
D         over-there
</screen>
          
        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.diff">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>diff</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn diff</refname>
          <refpurpose>This displays the differences between two revisions or paths.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>diff [-c M | -r N[:M]] [TARGET[@REV]...]</programlisting>
          <programlisting>diff [-r N[:M]] --old=OLD-TGT[@OLDREV] [--new=NEW-TGT[@NEWREV]] [PATH...]</programlisting>
          <programlisting>diff OLD-URL[@OLDREV] NEW-URL[@NEWREV]</programlisting>

        </refsect1>
        <refsect1>
          <title>Description</title>

          <itemizedlist>

            <listitem>
              <para>Display the differences between two paths.  You can
              use <command>svn diff</command> in the following ways:</para>
            </listitem>

            <listitem>
              <para>Use just <command>svn diff</command> to display local
                modifications in a working copy.</para>
            </listitem>

            <listitem>
              <para>Display the changes made to
                <replaceable>TARGET</replaceable>s as they are seen in
                <replaceable>REV</replaceable> between two revisions.
                <replaceable>TARGET</replaceable>s may be all working copy
                paths or all <replaceable>URL</replaceable>s.  If
                <replaceable>TARGET</replaceable>s are working copy paths,
                <replaceable>N</replaceable> defaults to
                <literal>BASE</literal> and <replaceable>M</replaceable>
                to the working copy; if <replaceable>TARGET</replaceable>s
                are <replaceable>URL</replaceable>s,
                <replaceable>N</replaceable> must be specified and
                <replaceable>M</replaceable> defaults to
                <literal>HEAD</literal>.  The <literal>-c M</literal> option
                is equivalent to <literal>-r N:M</literal> where <literal>N =
                M-1</literal>.  Using <literal>-c -M</literal> does the
                reverse: <literal>-r M:N</literal> where <literal>N =
                M-1</literal>.</para>
            </listitem>

            <listitem>
              <para>Display the differences between
                <replaceable>OLD-TGT</replaceable> as it was seen in
                <replaceable>OLDREV</replaceable> and
                <replaceable>NEW-TGT</replaceable> as it was seen in
                <replaceable>NEWREV</replaceable>.
                <replaceable>PATH</replaceable>s, if given, are relative
                to <replaceable>OLD-TGT</replaceable> and
                <replaceable>NEW-TGT</replaceable> and restrict the output
                to differences for those paths.
                <replaceable>OLD-TGT</replaceable> and
                <replaceable>NEW-TGT</replaceable> may be working copy
                paths or <replaceable>URL[@REV]</replaceable>.
                <replaceable>NEW-TGT</replaceable> defaults to
                <replaceable>OLD-TGT</replaceable> if not specified.
                <literal>-r N</literal>
                makes <replaceable>OLDREV</replaceable> default to
                <literal>N</literal>; <literal>-r N:M</literal>
                makes <replaceable>OLDREV</replaceable> default to
                <replaceable>N</replaceable> and
                <replaceable>NEWREV</replaceable> default to
                <replaceable>M</replaceable>.</para>
            </listitem>

          </itemizedlist>

          <para><userinput>svn diff OLD-URL[@OLDREV]
            NEW-URL[@NEWREV]</userinput> is shorthand for <userinput>svn
            diff --old=OLD-URL[@OLDREV]
            --new=NEW-URL[@NEWREV].</userinput></para>

          <para><userinput>svn diff -r N:M URL</userinput> is shorthand
            for <userinput>svn diff -r N:M --old=URL
            --new=URL</userinput>.</para>

          <para><userinput>svn diff [-r N[:M]] URL1[@N]
            URL2[@M]</userinput> is shorthand for <userinput>svn diff [-r
            N[:M]] --old=URL1 --new=URL2</userinput>.</para>

          <para>If <replaceable>TARGET</replaceable> is a URL, then
            revs <literal>N</literal> and <literal>M</literal> can be given either via the
            <option>--revision</option> option or by using the
            <quote>@</quote> notation as described earlier.</para>

          <para>If <replaceable>TARGET</replaceable> is a working copy
            path, the default behavior (when no
            <option>--revision</option> option is provided) is to
            display the differences between the base and working
            copies of <replaceable>TARGET</replaceable>.  If a
            <option>--revision</option> option is specified in this
            scenario, though, it means:</para>

          <variablelist>

            <varlistentry>
              <term><option>--revision N:M</option></term>
              <listitem>
                <para>The server compares
                  <replaceable>TARGET@N</replaceable>
                  and
                  <replaceable>TARGET@M</replaceable>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><option>--revision N</option></term>
              <listitem>
                <para>The client compares
                  <replaceable>TARGET@N</replaceable>
                  against the working copy.</para>
              </listitem>
            </varlistentry>

          </variablelist>

          <para>If the alternate syntax is used, the server compares
            <replaceable>URL1</replaceable> and
            <replaceable>URL2</replaceable> at revisions
            <replaceable>N</replaceable> and
            <replaceable>M</replaceable>, respectively.  If either
            <replaceable>N</replaceable> or
            <replaceable>M</replaceable> is omitted, a value of
            <literal>HEAD</literal> is assumed.</para>

          <para>By default, <command>svn diff</command> ignores the
            ancestry of files and merely compares the contents of the
            two files being compared.  If you use
            <option>--notice-ancestry</option>, the ancestry of the
            paths in question will be taken into consideration when
            comparing revisions (i.e., if you run <command>svn
            diff</command> on two files with identical contents but
            different ancestry, you will see the entire contents of
            the file as having been removed and added again).</para>

        </refsect1>
        <refsect1>
          <title>Alternate names</title>
          <para><command>di</command></para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Nothing</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>For obtaining differences against anything but
            <literal>BASE</literal> revision in your working copy</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--change (-c) ARG
--changelist ARG
--depth ARG
--diff-cmd CMD
--extensions (-x) "ARGS"
--force
--new ARG
--no-diff-deleted
--notice-ancestry
--old ARG
--revision (-r) ARG
--summarize
--xml
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>Compare <literal>BASE</literal> and your working copy
            (one of the most popular uses of <command>svn
            diff</command>):</para>

          <screen>
$ svn diff COMMITTERS 
Index: COMMITTERS
===================================================================
--- COMMITTERS	(revision 4404)
+++ COMMITTERS	(working copy)
</screen>

          <para>See what changed in the file
            <filename>COMMITTERS</filename> revision 9115:</para>

          <screen>
$ svn diff -c 9115 COMMITTERS 
Index: COMMITTERS
===================================================================
--- COMMITTERS	(revision 3900)
+++ COMMITTERS	(working copy)
</screen>


          <para>See how your working copy's modifications compare
            against an older revision:</para>

          <screen>
$ svn diff -r 3900 COMMITTERS 
Index: COMMITTERS
===================================================================
--- COMMITTERS	(revision 3900)
+++ COMMITTERS	(working copy)
</screen>

          <para>Compare revision 3000 to revision 3500 using <quote>@</quote>
            syntax:</para>

          <screen>
$ svn diff http://svn.collab.net/repos/svn/trunk/COMMITTERS@3000 \
           http://svn.collab.net/repos/svn/trunk/COMMITTERS@3500
Index: COMMITTERS
===================================================================
--- COMMITTERS	(revision 3000)
+++ COMMITTERS	(revision 3500)
&hellip;
</screen>

          <para>Compare revision 3000 to revision 3500 using range
            notation (pass only the one URL in this
            case):</para>

          <screen>
$ svn diff -r 3000:3500 http://svn.collab.net/repos/svn/trunk/COMMITTERS
Index: COMMITTERS
===================================================================
--- COMMITTERS	(revision 3000)
+++ COMMITTERS	(revision 3500)
</screen>


          <para>Compare revision 3000 to revision 3500 of all the files in
            <filename>trunk</filename> using range notation:</para>

          <screen>
$ svn diff -r 3000:3500 http://svn.collab.net/repos/svn/trunk
          </screen>


          <para>Compare revision 3000 to revision 3500 of only three
            files in <filename>trunk</filename> using range
            notation:</para>

          <screen>
$ svn diff -r 3000:3500 --old http://svn.collab.net/repos/svn/trunk \
           COMMITTERS README HACKING
          </screen>

          <para>If you have a working copy, you can obtain the
            differences without typing in the long URLs:</para>

          <screen>
$ svn diff -r 3000:3500 COMMITTERS 
Index: COMMITTERS
===================================================================
--- COMMITTERS	(revision 3000)
+++ COMMITTERS	(revision 3500)
</screen>

          <para>Use <option>--diff-cmd</option>
            <replaceable>CMD</replaceable> <option>-x</option> to
            pass arguments directly to the external diff
            program:</para>
          
          <screen>
$ svn diff --diff-cmd /usr/bin/diff -x "-i -b" COMMITTERS 
Index: COMMITTERS
===================================================================
0a1,2
&gt; This is a test
&gt; 
</screen>

          <para>Lastly, you can use the <option>--xml</option> option
            along with the <option>--summarize</option> option to view
            XML describing the changes that occurred between
            revisions, but not the contents of the diff itself:</para>
          
          <screen>
$ svn diff --summarize --xml http://svn.red-bean.com/repos/test@r2 \
           http://svn.red-bean.com/repos/test
&lt;?xml version="1.0"?&gt;
&lt;diff&gt;
&lt;paths&gt;
&lt;path
   props="none"
   kind="file"
   item="modified"&amp;gt;http://svn.red-bean.com/repos/test/sandwich.txt&amp;lt;/path&amp;gt;
&lt;path
   props="none"
   kind="file"
   item="deleted"&amp;gt;http://svn.red-bean.com/repos/test/burrito.txt&amp;lt;/path&amp;gt;
&lt;path
   props="none"
   kind="dir"
   item="added"&amp;gt;http://svn.red-bean.com/repos/test/snacks&amp;lt;/path&amp;gt;
&lt;/paths&gt;
&lt;/diff&gt;
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.export">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>export</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn export</refname>
          <refpurpose>Export a clean directory tree.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn export [-r REV] URL[@PEGREV] [PATH]</programlisting>
          <programlisting>svn export [-r REV] PATH1[@PEGREV] [PATH2]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>The first form exports a clean directory tree from the
            repository specified by <replaceable>URL</replaceable>&mdash;at revision
            <replaceable>REV</replaceable> if it is given; otherwise,
            at <literal>HEAD</literal>, into
            <replaceable>PATH</replaceable>.  If
            <replaceable>PATH</replaceable> is omitted, the last
            component of the <replaceable>URL</replaceable> is used
            for the local directory name.</para>

          <para>The second form exports a clean directory tree from
            the working copy specified by
            <replaceable>PATH1</replaceable> into
            <replaceable>PATH2</replaceable>.  All local changes will
            be preserved, but files not under version control will not
            be copied.</para>
        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para>None</para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Local disk</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Only if exporting from a URL</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--depth ARG
--force
--ignore-externals
--native-eol EOL
--quiet (-q)
--revision (-r) REV
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>Export from your working copy (doesn't print every
            file and directory):</para>

          <screen>
$ svn export a-wc my-export
Export complete.
</screen>

          <para>Export directly from the repository (prints every
            file and directory):</para>

          <screen>
$ svn export file:///var/svn/repos my-export
A  my-export/test
A  my-export/quiz
&hellip;
Exported revision 15.
</screen>

          <para>When rolling operating-system-specific release
            packages, it can be useful to export a tree that uses a
            specific EOL character for line endings.  The
            <option>--native-eol</option> option will do this, but it
            affects only files that have <literal>svn:eol-style =
            native</literal> properties attached to them.  For
            example, to export a tree with all CRLF line endings
            (possibly for a Windows <filename>.zip</filename> file
            distribution):</para>

          <screen>
$ svn export file:///var/svn/repos my-export --native-eol CRLF
A  my-export/test
A  my-export/quiz
&hellip;
Exported revision 15.
</screen>

          <para>You can specify <literal>LR</literal>,
            <literal>CR</literal>, or <literal>CRLF</literal> as a
            line-ending type with the <option>--native-eol</option>
            option.</para>

        </refsect1>
      </refentry>



      <refentry id="svn.ref.svn.c.help">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>help</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn help</refname>
          <refpurpose>Help!</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn help [SUBCOMMAND...]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>This is your best friend when you're using
            Subversion and this book isn't within reach!</para>
        </refsect1>
        
        <refsect1>
          <title>Alternate names</title>
          <para><command>?</command>, <command>h</command></para>
          <para>The options <option>-?</option>, <option>-h</option>,
            and <option>--help</option> have the same effect as using the
            <command>help</command> subcommand.</para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Nothing</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>No</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
</screen>
        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.import">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>import</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn import</refname>
          <refpurpose>Commit an unversioned file or tree into the 
            repository.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn import [PATH] URL</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Recursively commit a copy of
            <replaceable>PATH</replaceable> to
            <replaceable>URL</replaceable>.  If
            <replaceable>PATH</replaceable> is omitted,
            <quote><filename>.</filename></quote> is assumed.  Parent
            directories are created in the repository as necessary.
            Unversionable items such as device files and pipes are
            ignored even if <option>--force</option> is
            specified.</para>
        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para>None</para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Repository</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Yes</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--auto-props
--depth ARG
--editor-cmd EDITOR
--encoding ENC
--file (-F) FILE
--force
--force-log
--message (-m) TEXT
--no-auto-props
--no-ignore
--quiet (-q)
--with-revprop ARG
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>This imports the local directory
            <filename>myproj</filename> into
            <filename>trunk/misc</filename> in your repository.  The
            directory <filename>trunk/misc</filename> need not exist
            before you import into it&mdash;<command>svn
            import</command> will recursively create directories for
            you.</para>

          <screen>
$ svn import -m "New import" myproj \
             http://svn.red-bean.com/repos/trunk/misc
Adding         myproj/sample.txt
&hellip;
Transmitting file data .........
Committed revision 16.
</screen>

          <para>Be aware that this will <emphasis>not</emphasis>
            create a directory named <filename>myproj</filename> in
            the repository.  If that's what you want, simply add
            <filename>myproj</filename> to the end of the URL:</para>

          <screen>
$ svn import -m "New import" myproj \
            http://svn.red-bean.com/repos/trunk/misc/myproj
Adding         myproj/sample.txt
&hellip;
Transmitting file data .........
Committed revision 16.
</screen>

          <para>After importing data, note that the original tree is
            <emphasis>not</emphasis> under version control.  To start
            working, you still need to <command>svn checkout</command>
            a fresh working copy of the tree.</para>
          
        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.info">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>info</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn info</refname>
          <refpurpose>Display information about a local or remote 
            item.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn info [TARGET[@REV]...]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Print information about the working copy paths or
           URLs specified.  The information shown for both may
           include:</para>

          <itemizedlist>
            <listitem><para>Path</para></listitem>
            <listitem><para>Name</para></listitem>
            <listitem><para>URL</para></listitem>
            <listitem><para>Repository root</para></listitem>
            <listitem><para>Repository UUID</para></listitem>
            <listitem><para>Revision</para></listitem>
            <listitem><para>Node kind</para></listitem>
            <listitem><para>Last changed author</para></listitem>
            <listitem><para>Last changed revision</para></listitem>
            <listitem><para>Last changed date</para></listitem>
            <listitem><para>Lock token</para></listitem>
            <listitem><para>Lock owner</para></listitem>
            <listitem><para>Lock created (date)</para></listitem>
            <listitem><para>Lock expires (date)</para></listitem>
          </itemizedlist>

          <para>Additional kinds of information available only for
            working copy paths are:</para>

          <itemizedlist>
            <listitem><para>Schedule</para></listitem>
            <listitem><para>Copied from URL</para></listitem>
            <listitem><para>Copied from rev</para></listitem>
            <listitem><para>Text last updated</para></listitem>
            <listitem><para>Properties last updated</para></listitem>
            <listitem><para>Checksum</para></listitem>
            <listitem><para>Conflict previous base file</para></listitem>
            <listitem><para>Conflict previous working file</para></listitem>
            <listitem><para>Conflict current base file</para></listitem>
            <listitem><para>Conflict properties file</para></listitem>
          </itemizedlist>
        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para>None</para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Nothing</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Only if operating on URLs</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--changelist ARG
--depth ARG
--incremental
--recursive (-R)
--revision (-r) REV
--targets FILENAME
--xml
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para><command>svn info</command> will show you all the
            useful information that it has for items in your working
            copy.  It will show information for files:</para>

          <screen>
$ svn info foo.c
Path: foo.c
Name: foo.c
URL: http://svn.red-bean.com/repos/test/foo.c
Repository Root: http://svn.red-bean.com/repos/test
Repository UUID: 5e7d134a-54fb-0310-bd04-b611643e5c25
Revision: 4417
Node Kind: file
Schedule: normal
Last Changed Author: sally
Last Changed Rev: 20
Last Changed Date: 2003-01-13 16:43:13 -0600 (Mon, 13 Jan 2003)
Text Last Updated: 2003-01-16 21:18:16 -0600 (Thu, 16 Jan 2003)
Properties Last Updated: 2003-01-13 21:50:19 -0600 (Mon, 13 Jan 2003)
Checksum: d6aeb60b0662ccceb6bce4bac344cb66
</screen>

          <para>It will also show information for directories:</para>

          <screen>
$ svn info vendors
Path: vendors
URL: http://svn.red-bean.com/repos/test/vendors
Repository Root: http://svn.red-bean.com/repos/test
Repository UUID: 5e7d134a-54fb-0310-bd04-b611643e5c25
Revision: 19
Node Kind: directory
Schedule: normal
Last Changed Author: harry
Last Changed Rev: 19
Last Changed Date: 2003-01-16 23:21:19 -0600 (Thu, 16 Jan 2003)
Properties Last Updated: 2003-01-16 23:39:02 -0600 (Thu, 16 Jan 2003)
</screen>

           <para><command>svn info</command> also acts on URLs (also
             note that the file <filename>readme.doc</filename> in
             this example is locked, so lock information is also
             provided):</para>

           <screen>
$ svn info http://svn.red-bean.com/repos/test/readme.doc
Path: readme.doc
Name: readme.doc
URL: http://svn.red-bean.com/repos/test/readme.doc
Repository Root: http://svn.red-bean.com/repos/test
Repository UUID: 5e7d134a-54fb-0310-bd04-b611643e5c25
Revision: 1
Node Kind: file
Schedule: normal
Last Changed Author: sally
Last Changed Rev: 42
Last Changed Date: 2003-01-14 23:21:19 -0600 (Tue, 14 Jan 2003)
Lock Token: opaquelocktoken:14011d4b-54fb-0310-8541-dbd16bd471b2
Lock Owner: harry
Lock Created: 2003-01-15 17:35:12 -0600 (Wed, 15 Jan 2003)
Lock Comment (1 line):
My test lock comment
</screen>

           <para>Lastly, <command>svn info</command> output is
             available in XML format by passing
             the<option>--xml</option> option:</para>

           <screen>
$ svn info --xml http://svn.red-bean.com/repos/test
&lt;?xml version="1.0"?&gt;
&lt;info&gt;
&lt;entry
   kind="dir"
   path="."
   revision="1"&gt;
&lt;url&gt;http://svn.red-bean.com/repos/test&lt;/url&gt;
&lt;repository&gt;
&lt;root&gt;http://svn.red-bean.com/repos/test&lt;/root&gt;
&lt;uuid&gt;5e7d134a-54fb-0310-bd04-b611643e5c25&lt;/uuid&gt;
&lt;/repository&gt;
&lt;wc-info&gt;
&lt;schedule&gt;normal&lt;/schedule&gt;
&lt;depth&gt;infinity&lt;/depth&gt;
&lt;/wc-info&gt;
&lt;commit
   revision="1"&gt;
&lt;author&gt;sally&lt;/author&gt;
&lt;date&gt;2003-01-15T23:35:12.847647Z&lt;/date&gt;
&lt;/commit&gt;
&lt;/entry&gt;
&lt;/info&gt;
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.list">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>list</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn list</refname>
          <refpurpose>List directory entries in the repository.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn list [TARGET[@REV]...]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>List each <replaceable>TARGET</replaceable> file and
            the contents of each <replaceable>TARGET</replaceable>
            directory as they exist in the repository.  If
            <replaceable>TARGET</replaceable> is a working copy path,
            the corresponding repository URL will be used.</para>

          <para>The default <replaceable>TARGET</replaceable> is
            <quote><filename>.</filename></quote>, meaning the
            repository URL of the current working copy
            directory.</para>

          <para>With <option>--verbose</option>, <command>svn
            list</command> shows the following fields for each
            item:</para>

          <itemizedlist>
            <listitem><para>Revision number of the last
              commit</para></listitem>

            <listitem><para>Author of the last commit</para></listitem>

            <listitem><para>If locked, the letter <quote>O</quote> (see the preceding section on <xref
              linkend="svn.ref.svn.c.info"/> for details).</para></listitem>

            <listitem><para>Size (in bytes)</para></listitem>

            <listitem><para>Date and time of the last
              commit</para></listitem>
          </itemizedlist>

          <para>With <option>--xml</option>, output is in XML format (with
            a header and an enclosing document element unless
            <option>--incremental</option> is also specified).  All of the
            information is present; the <option>--verbose</option> option
            is not accepted.</para>
        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para><command>ls</command></para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Nothing</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Yes</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--depth ARG
--incremental
--recursive (-R)
--revision (-r) REV
--verbose (-v)
--xml
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para><command>svn list</command> is most useful if you
            want to see what files a repository has without
            downloading a working copy:</para>

          <screen>
$ svn list http://svn.red-bean.com/repos/test/support
README.txt
INSTALL
examples/
&hellip;
</screen>

          <para>You can pass the <option>--verbose</option> option for
            additional information, rather like the Unix command
            <command>ls -l</command>:</para>

          <screen>
$ svn list --verbose file:///var/svn/repos
     16 sally         28361 Jan 16 23:18 README.txt
     27 sally             0 Jan 18 15:27 INSTALL
     24 harry               Jan 18 11:27 examples/
</screen>

          <para>You can also get <command>svn list</command> output in
            XML format with the <option>--xml</option> option:</para>

          <screen>
$ svn list --xml http://svn.red-bean.com/repos/test
&lt;?xml version="1.0"?&gt;
&lt;lists&gt;
&lt;list
   path="http://svn.red-bean.com/repos/test"&gt;
&lt;entry
   kind="dir"&gt;
&lt;name&gt;examples&lt;/name&gt;
&lt;size&gt;0&lt;/size&gt;
&lt;commit
   revision="24"&gt;
&lt;author&gt;harry&lt;/author&gt;
&lt;date&gt;2008-01-18T06:35:53.048870Z&lt;/date&gt;
&lt;/commit&gt;
&lt;/entry&gt;
...
&lt;/list&gt;
&lt;/lists&gt;
</screen>

          <para>For further details, see the earlier section <xref
            linkend="svn.tour.history.browsing.list"/>.</para>

        </refsect1>
      </refentry>


      <refentry id="svn.ref.svn.c.lock">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>lock</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn lock</refname> 
            <refpurpose>Lock working copy paths or URLs in the
              repository so that no other user can commit changes to
              them.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn lock TARGET...</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Lock each <replaceable>TARGET</replaceable>.  If any
            <replaceable>TARGET</replaceable> is already locked by
            another user, print a warning and continue locking the
            rest of the <replaceable>TARGET</replaceable>s.  Use
            <option>--force</option> to steal a lock from another user
            or working copy.</para>

        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para>None</para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Working copy, repository</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Yes</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--encoding ENC
--file (-F) FILE
--force
--force-log
--message (-m) TEXT
--targets FILENAME
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>Lock two files in your working copy:</para>

          <screen>
$ svn lock tree.jpg house.jpg
'tree.jpg' locked by user 'harry'.
'house.jpg' locked by user 'harry'.
</screen>

          <para>Lock a file in your working copy that is currently
            locked by another user:</para>

          <screen>
$ svn lock tree.jpg
svn: warning: Path '/tree.jpg is already locked by user 'sally in \
     filesystem '/var/svn/repos/db'

$ svn lock --force tree.jpg
'tree.jpg' locked by user 'harry'.
</screen>

          <para>Lock a file without a working copy:</para>

          <screen>
$ svn lock http://svn.red-bean.com/repos/test/tree.jpg
'tree.jpg' locked by user 'harry'.
</screen>

          <para>For further details, see <xref
            linkend="svn.advanced.locking"/>.</para>

        </refsect1>
      </refentry>


      <refentry id="svn.ref.svn.c.log">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>log</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn log</refname>
          <refpurpose>Display commit log messages.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn log [PATH]</programlisting>
          <programlisting>svn log URL[@REV] [PATH...]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Shows log messages from the repository.
            If no arguments are supplied, <command>svn
            log</command> shows the log messages for all files and
            directories inside (and including) the current working
            directory of your working copy.  You can refine the
            results by specifying a path, one or more revisions, or
            any combination of the two.  The default revision range
            for a local path is <literal>BASE:1</literal>.</para>

          <para>If you specify a URL alone, it prints log
            messages for everything the URL contains.  If you
            add paths past the URL, only messages for those paths
            under that URL will be printed.  The default revision range
            for a URL is <literal>HEAD:1</literal>.</para>

          <para>With <option>--verbose</option>, <command>svn log</command>
            will also print all affected paths with each log message.
            With <option>--quiet</option>, <command>svn log</command>
            will not print the log message body itself (this is
            compatible with <option>--verbose</option>).</para>

          <para>Each log message is printed just once, even if more
            than one of the affected paths for that revision were
            explicitly requested.  Logs follow copy history by
            default.  Use <option>--stop-on-copy</option> to disable
            this behavior, which can be useful for determining branch
            points.</para>

        </refsect1>
        <refsect1>
          <title>Alternate names</title>
          <para>None</para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Nothing</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Yes</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--change (-c) ARG
--incremental
--limit (-l) NUM
--quiet (-q)
--revision (-r) REV
--stop-on-copy
--targets FILENAME
--use-merge-history (-g)
--verbose (-v)
--with-all-revprops
--with-revprop ARG
--xml
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>You can see the log messages for all the paths that
            changed in your working copy by running <userinput>svn
            log</userinput> from the top:</para>

          <screen>
$ svn log
------------------------------------------------------------------------
r20 | harry | 2003-01-17 22:56:19 -0600 (Fri, 17 Jan 2003) | 1 line

Tweak.
------------------------------------------------------------------------
r17 | sally | 2003-01-16 23:21:19 -0600 (Thu, 16 Jan 2003) | 2 lines
&hellip;
</screen>

          <para>Examine all log messages for a particular file in
            your working copy:</para>

          <screen>
$ svn log foo.c
------------------------------------------------------------------------
r32 | sally | 2003-01-13 00:43:13 -0600 (Mon, 13 Jan 2003) | 1 line

Added defines.
------------------------------------------------------------------------
r28 | sally | 2003-01-07 21:48:33 -0600 (Tue, 07 Jan 2003) | 3 lines
&hellip;
</screen>

          <para>If you don't have a working copy handy, you can log
            a URL:</para>

          <screen>
$ svn log http://svn.red-bean.com/repos/test/foo.c
------------------------------------------------------------------------
r32 | sally | 2003-01-13 00:43:13 -0600 (Mon, 13 Jan 2003) | 1 line

Added defines.
------------------------------------------------------------------------
r28 | sally | 2003-01-07 21:48:33 -0600 (Tue, 07 Jan 2003) | 3 lines
&hellip;
</screen>

          <para>If you want several distinct paths underneath the
            same URL, you can use the <literal>URL [PATH...]</literal>
            syntax:</para>

          <screen>
$ svn log http://svn.red-bean.com/repos/test/ foo.c bar.c
------------------------------------------------------------------------
r32 | sally | 2003-01-13 00:43:13 -0600 (Mon, 13 Jan 2003) | 1 line

Added defines.
------------------------------------------------------------------------
r31 | harry | 2003-01-10 12:25:08 -0600 (Fri, 10 Jan 2003) | 1 line

Added new file bar.c
------------------------------------------------------------------------
r28 | sally | 2003-01-07 21:48:33 -0600 (Tue, 07 Jan 2003) | 3 lines
&hellip;
</screen>

          <para>The <option>--verbose</option> option causes
            <command>svn log</command> to include information about
            the paths that were changed in each displayed revision.
            These paths appear, one path per line of output, with
            action codes that indicate what type of change was made to
            the path.</para>

          <screen>
$ svn log -v http://svn.red-bean.com/repos/test/ foo.c bar.c
------------------------------------------------------------------------
r32 | sally | 2003-01-13 00:43:13 -0600 (Mon, 13 Jan 2003) | 1 line
Changed paths:
   M /foo.c

Added defines.
------------------------------------------------------------------------
r31 | harry | 2003-01-10 12:25:08 -0600 (Fri, 10 Jan 2003) | 1 line
Changed paths:
   A /bar.c

Added new file bar.c
------------------------------------------------------------------------
r28 | sally | 2003-01-07 21:48:33 -0600 (Tue, 07 Jan 2003) | 3 lines
&hellip;
</screen>

          <para><command>svn log</command> uses just a handful of action codes,
            and they are similar to the
            ones the <command>svn update</command>
            command uses:</para>

          <variablelist>
            <varlistentry>
              <term><literal>A</literal></term>
              <listitem><para>The item was added.</para></listitem>
            </varlistentry>
            <varlistentry>
              <term><literal>D</literal></term>
              <listitem><para>The item was deleted.</para></listitem>
            </varlistentry>
            <varlistentry>
              <term><literal>M</literal></term>
              <listitem><para>Properties or textual contents on the
                item were changed.</para></listitem>
            </varlistentry>
            <varlistentry>
              <term><literal>R</literal></term>
              <listitem><para>The item was replaced by a different one
                at the same location.</para></listitem>
            </varlistentry>
          </variablelist>

          <para>In addition to the action codes which precede the
            changed paths, <command>svn log</command> with the <option>--verbose</option> option will
            note whether a path was added or replaced as the result of a copy
            operation.  It does so by printing <literal>(from
            <replaceable>COPY-FROM-PATH</replaceable>:<replaceable>COPY-FROM-REV</replaceable>)</literal>
            after such paths.</para>

          <para>When you're concatenating the results of multiple
            calls to the log command, you may want to use the
            <option>--incremental</option> option. <command>svn
            log</command> normally prints out a dashed line at the
            beginning of a log message, after each subsequent log
            message, and following the final log message.  If you
            ran <command>svn log</command> on a range of two
            revisions, you would get this:</para>
          <screen>
$ svn log -r 14:15
------------------------------------------------------------------------
r14 | &hellip;

------------------------------------------------------------------------
r15 | &hellip;

------------------------------------------------------------------------
</screen>

          <para>However, if you wanted to gather two nonsequential log
            messages into a file, you might do something like
            this:</para>

          <screen>
$ svn log -r 14 &gt; mylog
$ svn log -r 19 &gt;&gt; mylog
$ svn log -r 27 &gt;&gt; mylog
$ cat mylog
------------------------------------------------------------------------
r14 | &hellip;

------------------------------------------------------------------------
------------------------------------------------------------------------
r19 | &hellip;

------------------------------------------------------------------------
------------------------------------------------------------------------
r27 | &hellip;

------------------------------------------------------------------------
</screen>

          <para>You can avoid the clutter of the double dashed lines
            in your output by using the <option>--incremental</option>
            option:</para>

          <screen>
$ svn log --incremental -r 14 &gt; mylog
$ svn log --incremental -r 19 &gt;&gt; mylog
$ svn log --incremental -r 27 &gt;&gt; mylog
$ cat mylog
------------------------------------------------------------------------
r14 | &hellip;

------------------------------------------------------------------------
r19 | &hellip;

------------------------------------------------------------------------
r27 | &hellip;
</screen>

          <para>The <option>--incremental</option> option provides
            similar output control when using the
            <option>--xml</option> option:</para>

          <screen>
$ svn log --xml --incremental -r 1 sandwich.txt
&lt;logentry
   revision="1"&gt;
&lt;author&gt;harry&lt;/author&gt;
&lt;date&gt;2008-06-03T06:35:53.048870Z&lt;/date&gt;
&lt;msg&gt;Initial Import.&lt;/msg&gt;
&lt;/logentry&gt;
</screen>

          <tip>
            <para>Sometimes when you run <command>svn log</command> on
              a specific path and a specific revision, you see no log
              information output at all, as in the following:</para>

            <screen>
$ svn log -r 20 http://svn.red-bean.com/untouched.txt
------------------------------------------------------------------------
</screen>

            <para>That just means the path wasn't modified in that
              revision.  To get log information for that revision,
              either run the log operation against the repository's
              root URL, or specify a path that you happen to know was
              changed in that revision:</para>
            
            <screen>
$ svn log -r 20 touched.txt 
------------------------------------------------------------------------
r20 | sally | 2003-01-17 22:56:19 -0600 (Fri, 17 Jan 2003) | 1 line

Made a change.
------------------------------------------------------------------------
</screen>
          </tip>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.merge">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>merge</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn merge</refname>
          <refpurpose>Apply the differences between two sources to a
          working copy path.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn merge sourceURL1[@N] sourceURL2[@M] [WCPATH]</programlisting>
          <programlisting>svn merge sourceWCPATH1@N sourceWCPATH2@M [WCPATH]</programlisting>
          <programlisting>svn merge [[-c M]... | [-r N:M]...] [SOURCE[@REV] [WCPATH]]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>In the first form, the source URLs are specified at
            revisions <replaceable>N</replaceable> and <replaceable>M</replaceable>.
            These are the two sources to be compared.  The revisions
            default to <literal>HEAD</literal> if omitted.</para>

          <para>In the second form, the URLs corresponding to the
            source working copy paths define the sources to be
            compared.  The revisions must be specified.</para>

          <para>In the third form, <replaceable>SOURCE</replaceable>
            can be either a URL or a working copy path (in which case
            its corresponding URL is used).  If not specified,
            <replaceable>SOURCE</replaceable> will be the same as
            <replaceable>WCPATH</replaceable>.
            <replaceable>SOURCE</replaceable> in revision
            <replaceable>REV</replaceable> is compared as it existed
            between revisions <replaceable>N</replaceable> and
            <replaceable>M</replaceable> for each revision range
            provided.  If <replaceable>REV</replaceable> is not
            specified, <literal>HEAD</literal> is assumed.</para>

          <para><literal>-c M</literal> is equivalent to <literal>-r
            &lt;M-1&gt;:M</literal>, and <literal>-c -M</literal> does
            the reverse: <literal>-r M:&lt;M-1&gt;</literal>.  If no
            revision ranges are specified, the default range of
            <literal>1:HEAD</literal> is used.  Multiple
            <literal>-c</literal> and/or <literal>-r</literal>
            instances may be specified, and mixing of forward and
            reverse ranges is allowed&mdash;the ranges are internally
            compacted to their minimum representation before merging
            begins (which may result in no-op).</para>

          <para><replaceable>WCPATH</replaceable> is the working copy
            path that will receive the changes.  If
            <replaceable>WCPATH</replaceable> is omitted, a default
            value of <quote><filename>.</filename></quote> is assumed,
            unless the sources have identical basenames that match a
            file within <quote><filename>.</filename></quote>.  In
            this case, the differences will be applied to that
            file.</para>

          <para>Subversion will internally track metadata about
            the merge operation only if the two sources are ancestrally
            related&mdash;if the first source is an ancestor of the
            second or vice versa.  This is guaranteed to be the case
            when using the third form.  Unlike <command>svn
            diff</command>, the merge command takes the ancestry of a
            file into consideration when performing a merge operation.
            This is very important when you're merging changes from
            one branch into another and you've renamed a file on one
            branch but not the other.</para>

        </refsect1>
        <refsect1>
          <title>Alternate names</title>
          <para>None</para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Working copy</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Only if working with URLs</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--accept ARG
--change (-c) REV
--depth ARG
--diff3-cmd CMD
--dry-run
--extensions (-x) ARG
--force
--ignore-ancestry
--quiet (-q)
--record-only
--reintegrate
--revision (-r) REV
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>Merge a branch back into the trunk (assuming that
            you have an up-to-date working copy of the trunk):</para>

          <screen>
$ svn merge --reintegrate \
            http://svn.example.com/repos/calc/branches/my-calc-branch
--- Merging differences between repository URLs into '.':
U    button.c
U    integer.c
U    Makefile
 U   .

$ # build, test, verify, ...

$ svn commit -m "Merge my-calc-branch back into trunk!"
Sending        .
Sending        button.c
Sending        integer.c
Sending        Makefile
Transmitting file data ..
Committed revision 391.
</screen>
          
        <para>To merge changes to a single file:</para>

        <screen>
$ cd myproj
$ svn merge -r 30:31 thhgttg.txt 
U  thhgttg.txt
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.mergeinfo">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>mergeinfo</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn mergeinfo</refname>
          <refpurpose>Query merge-related information.  See <xref
            linkend="svn.branchmerge.basicmerging.mergeinfo"/> for
            details.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn mergeinfo SOURCE_URL[@REV] [TARGET[@REV]...]</programlisting>

        </refsect1>
        <refsect1>
          <title>Description</title>
          <para>Query information related to merges (or potential
            merges) between <replaceable>SOURCE-URL</replaceable> and
            <replaceable>TARGET</replaceable>.  If
            the <option>--show-revs</option> option is not provided,
            display revisions which have been merged
            from <replaceable>SOURCE-URL</replaceable>
            to <replaceable>TARGET</replaceable>.  Otherwise, display
            either <literal>merged</literal>
            or <literal>eligible</literal> revisions as specified by
            the <option>--show-revs</option> option.</para>

        </refsect1>
        <refsect1>
          <title>Alternate names</title>
          <para>None</para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Nothing</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Yes</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--revision (-r) REV
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>Find out which changesets your trunk directory has
            already received as well as what changesets it's still
            eligible to receive:</para>

          <screen>
$ svn mergeinfo branches/test
Path: branches/test
  Source path: /trunk
    Merged ranges: r2:13
    Eligible ranges: r13:15
</screen>

        </refsect1>
      </refentry>


      <refentry id="svn.ref.svn.c.mkdir">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>mkdir</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn mkdir</refname>
          <refpurpose>Create a new directory under version control.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn mkdir PATH...</programlisting>
          <programlisting>svn mkdir URL...</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Create a directory with a name given by the final
            component of the <replaceable>PATH</replaceable> or <replaceable>URL</replaceable>.
            A directory specified by a working copy
            <replaceable>PATH</replaceable> is scheduled for addition
            in the working copy.  A directory specified by a URL is
            created in the repository via an immediate commit.
            Multiple directory URLs are committed atomically.  In both
            cases, all the intermediate directories must already exist
            unless the <option>--parents</option> option is
            used.</para>
        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para>None</para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Working copy; repository if operating on a URL</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Only if operating on a URL</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--editor-cmd EDITOR
--encoding ENC
--file (-F) FILE
--force-log
--message (-m) TEXT
--parents
--quiet (-q)
--with-revprop ARG
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>Create a directory in your working copy:</para>

          <screen>
$ svn mkdir newdir
A         newdir
</screen>

          <para>Create one in the repository (this is an instant commit, so a
            log message is required):</para>

          <screen>
$ svn mkdir -m "Making a new dir." http://svn.red-bean.com/repos/newdir

Committed revision 26.
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.move">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>move</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn move</refname>
          <refpurpose>Move a file or directory.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn move SRC... DST</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>This command moves files or directories in your
            working copy or in the repository.</para>

          <tip>
            <para>This command is equivalent to an <command>svn
              copy</command> followed by <command>svn
              delete</command>.</para>
          </tip>

          <para>When moving multiple sources, they will be added as
            children of <replaceable>DST</replaceable>, which must be
            a directory.</para>

          <note>
            <para>Subversion does not support moving between working
              copies and URLs.  In addition, you can only move files
              within a single repository&mdash;Subversion does not
              support cross-repository moving.  Subversion supports
              the following types of moves within a single repository:</para>
          </note>

          <variablelist>

            <varlistentry>
              <term>WC &rarr; WC</term>
              <listitem>
                <para>Move and schedule a file or directory for
                  addition (with history).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>URL &rarr; URL</term>
              <listitem>
                <para>Complete server-side rename.</para>
              </listitem>
            </varlistentry>

          </variablelist>
        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para><command>mv</command>, <command>rename</command>, <command>ren</command></para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Working copy; repository if operating on a URL</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Only if operating on a URL</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--editor-cmd EDITOR
--encoding ENC
--file (-F) FILE
--force
--force-log
--message (-m) TEXT
--parents
--quiet (-q)
--revision (-r) REV
--with-revprop ARG
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>Move a file in your working copy:</para>

          <screen>
$ svn move foo.c bar.c
A         bar.c
D         foo.c
</screen>

          <para>Move several files in your working copy into a
            subdirectory:</para>

          <screen>
$ svn move baz.c bat.c qux.c src
A         src/baz.c
D         baz.c
A         src/bat.c
D         bat.c
A         src/qux.c
D         qux.c
</screen>

          <para>Move a file in the repository (this is an immediate commit,
            so it requires a commit message):</para>

          <screen>
$ svn move -m "Move a file" http://svn.red-bean.com/repos/foo.c \
                            http://svn.red-bean.com/repos/bar.c

Committed revision 27.
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.propdel">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>propdel</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn propdel</refname>
          <refpurpose>Remove a property from an item.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn propdel PROPNAME [PATH...]</programlisting>
          <programlisting>svn propdel PROPNAME --revprop -r REV [TARGET]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>This removes properties from files, directories, or
            revisions.  The first form removes versioned properties in
            your working copy, and the second removes unversioned
            remote properties on a repository revision
            (<replaceable>TARGET</replaceable> determines only which
            repository to access).</para>
        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para><command>pdel</command>, <command>pd</command></para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Working copy; repository only if operating on a URL</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Only if operating on a URL</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--changelist ARG
--depth ARG
--quiet (-q)
--recursive (-R)
--revision (-r) REV
--revprop
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>Delete a property from a file in your working
            copy:</para>

          <screen>
$ svn propdel svn:mime-type some-script
property 'svn:mime-type' deleted from 'some-script'.
</screen>

          <para>Delete a revision property:</para>

          <screen>
$ svn propdel --revprop -r 26 release-date 
property 'release-date' deleted from repository revision '26'
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.propedit">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>propedit</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn propedit</refname>
          <refpurpose>Edit the property of one or more items under
            version control. See <xref
            linkend="svn.ref.svn.c.propset"/> later in this chapter.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn propedit PROPNAME TARGET...</programlisting>
          <programlisting>svn propedit PROPNAME --revprop -r REV [TARGET]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Edit one or more properties using your favorite
            editor.  The first form edits versioned properties in
            your working copy, and the second edits unversioned
            remote properties on a repository revision
            (<replaceable>TARGET</replaceable> determines only which
            repository to access).</para>
        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para><command>pedit</command>, <command>pe</command></para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Working copy; repository only if operating on a URL</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Only if operating on a URL</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--editor-cmd EDITOR
--encoding ENC
--file (-F) ARG
--force
--force-log
--message (-m) ARG
--revision (-r) REV
--revprop
--with-revprop ARG
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para><command>svn propedit</command> makes it easy to
            modify properties that have multiple values:</para>

          <screen>
$ svn propedit svn:keywords  foo.c 
    &lt;svn will launch your favorite editor here, with a buffer open
    containing the current contents of the svn:keywords property.  You
    can add multiple values to a property easily here by entering one
    value per line.&gt;
Set new value for property 'svn:keywords' on 'foo.c'
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.propget">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>propget</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn propget</refname>
          <refpurpose>Print the value of a property.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn propget PROPNAME [TARGET[@REV]...]</programlisting>
          <programlisting>svn propget PROPNAME --revprop -r REV [URL]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Print the value of a property on files,
            directories, or revisions.  The first form prints the
            versioned property of an item or items in your working
            copy, and the second prints unversioned remote
            properties on a repository revision.  See <xref
            linkend="svn.advanced.props"/> for more information on
            properties.</para>
        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para><command>pget</command>, <command>pg</command></para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Working copy; repository only if operating on a URL</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Only if operating on a URL</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--changelist ARG
--depth ARG
--recursive (-R)
--revision (-r) REV
--revprop
--strict
--xml
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>Examine a property of a file in your working
            copy:</para>
          
          <screen>
$ svn propget svn:keywords foo.c
Author
Date
Rev
</screen>

          <para>The same goes for a revision property:</para>

          <screen>
$ svn propget svn:log --revprop -r 20 
Began journal.
</screen>

          <para>Lastly, you can get <command>svn propget</command>
            output in XML format with the <option>--xml</option>
            option:</para>

          <screen>
$ svn propget --xml svn:ignore .
&lt;?xml version="1.0"?&gt;
&lt;properties&gt;
&lt;target
   path=""&gt;
&lt;property
   name="svn:ignore"&gt;*.o
&lt;/property&gt;
&lt;/target&gt;
&lt;/properties&gt;
</screen>
          
        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.proplist">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>proplist</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn proplist</refname>
          <refpurpose>List all properties.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn proplist [TARGET[@REV]...]</programlisting>
          <programlisting>svn proplist --revprop -r REV [TARGET]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>List all properties on files, directories, or
            revisions.  The first form lists versioned properties in
            your working copy, and the second lists unversioned remote
            properties on a repository revision
            (<replaceable>TARGET</replaceable> determines only which
            repository to access).</para>
        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para><command>plist</command>, <command>pl</command></para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Working copy; repository only if operating on a URL</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Only if operating on a URL</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--changelist ARG
--depth ARG
--quiet (-q)
--recursive (-R)
--revision (-r) REV
--revprop
--verbose (-v)
--xml
</screen>
        </refsect1>
        
        <refsect1>
          <title>Examples</title>

          <para>You can use <command>proplist</command> to see the properties on an
            item in your working copy:</para>

          <screen>
$ svn proplist foo.c
Properties on 'foo.c':
  svn:mime-type
  svn:keywords
  owner
</screen>

          <para>But with the <option>--verbose</option> flag, <command>svn
            proplist</command> is extremely handy as it also shows you the
            values for the properties:</para>

          <screen>
$ svn proplist --verbose foo.c
Properties on 'foo.c':
  svn:mime-type : text/plain
  svn:keywords : Author Date Rev
  owner : sally
</screen>

          <para>Lastly, you can get <command>svn proplist</command>
            output in xml format with the <option>--xml</option>
            option:</para>

          <screen>
$ svn proplist --xml 
&lt;?xml version="1.0"?&gt;
&lt;properties&gt;
&lt;target
   path="."&gt;
&lt;property
   name="svn:ignore"/&gt;
&lt;/target&gt;
&lt;/properties&gt;
</screen>
          
        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.propset">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>propset</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn propset</refname>
          <refpurpose>Set <replaceable>PROPNAME</replaceable> to <replaceable>PROPVAL</replaceable> on files, directories, or revisions.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn propset PROPNAME [PROPVAL | -F VALFILE] PATH...</programlisting>
          <programlisting>svn propset PROPNAME --revprop -r REV [PROPVAL | -F VALFILE] [TARGET]</programlisting>
        </refsect1>

        <refsect1>
          <title>Description</title>

          <para>Set <replaceable>PROPNAME</replaceable> to
            <replaceable>PROPVAL</replaceable> on files, directories,
            or revisions.  The first example creates a versioned, local
            property change in the working copy, and the second
            creates an unversioned, remote property change on a
            repository revision
            (<replaceable>TARGET</replaceable> determines only which
            repository to access).</para>

          <tip>
            <para>Subversion has a number of <quote>special</quote>
              properties that affect its behavior.  See <xref
              linkend="svn.ref.properties"/> later in this chapter for more on these
              properties.</para>
          </tip>

        </refsect1>
        <refsect1>
          <title>Alternate names</title>
          <para><replaceable>pset</replaceable>, <replaceable>ps</replaceable></para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Working copy; repository only if operating on a URL</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Only if operating on a URL</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--changelist ARG
--depth ARG
--encoding ENC
--file (-F) FILE
--force
--quiet (-q)
--recursive (-R)
--revision (-r) REV
--revprop
--targets FILENAME
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>Set the MIME type for a file:</para>

          <screen>
$ svn propset svn:mime-type image/jpeg foo.jpg 
property 'svn:mime-type' set on 'foo.jpg'
</screen>

          <para>On a Unix system, if you want a file to have the
            executable permission set:</para>

          <screen>
$ svn propset svn:executable ON somescript
property 'svn:executable' set on 'somescript'
</screen>

          <para>Perhaps you have an internal policy to set certain
            properties for the benefit of your coworkers:</para>

          <screen>
$ svn propset owner sally foo.c
property 'owner' set on 'foo.c'
</screen>

          <para>If you made a mistake in a log message for a
            particular revision and want to change it, use
            <option>--revprop</option> and set <literal>svn:log</literal>
            to the new log message:</para>

          <screen>
$ svn propset --revprop -r 25 svn:log "Journaled about trip to New York."
property 'svn:log' set on repository revision '25'
</screen>

          <para>Or, if you don't have a working copy, you can
            provide a URL:</para>
          
          <screen>
$ svn propset --revprop -r 26 svn:log "Document nap." \
              http://svn.red-bean.com/repos
property 'svn:log' set on repository revision '25'
</screen>

          <para>Lastly, you can tell <command>propset</command> to take its input from
            a file.  You could even use this to set the contents of a
            property to something binary:</para>

          <screen>
$ svn propset owner-pic -F sally.jpg moo.c 
property 'owner-pic' set on 'moo.c'
</screen>

          <note>
            <para>By default, you cannot modify revision properties
              in a Subversion repository.  Your repository
              administrator must explicitly enable revision property
              modifications by creating a hook named
              <literal>pre-revprop-change</literal>.  See <xref
              linkend="svn.reposadmin.create.hooks"/> for more information on
              hook scripts.</para>
          </note>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.resolve">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>resolve</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn resolve</refname>
          <refpurpose>Resolve conflicts on working copy files or
            directories.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn resolve PATH...</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Resolve <quote>conflicted</quote> state on working
            copy files or directories.  This routine does not
            semantically resolve conflict markers; however, it
            replaces <replaceable>PATH</replaceable> with the version
            specified by the <option>--accept</option> argument and
            then removes conflict-related artifact files.  This allows
            <replaceable>PATH</replaceable> to be committed
            again&mdash;that is, it tells Subversion that the
            conflicts have been
            <quote>resolved.</quote>.  You can pass the following
            arguments to the <option>--accept</option> command
            depending on your desired resolution:</para>

          <variablelist>

            <varlistentry>
              <term><literal>base</literal></term>
              <listitem>
                <para>Choose the file that was the
                  <literal>BASE</literal> revision before you updated
                  your working copy.  That is, the file that you
                  checked out before you made your latest
                  edits.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>working</literal></term>
              <listitem>
                <para>Assuming that you've manually handled the
                conflict resolution, choose the version of the file as
                it currently stands in your working copy.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>mine-full</literal></term>
              <listitem>
                <para>Resolve all conflicted files with copies of the
                files as they stood immediately before you
                ran <command>svn update</command>.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>theirs-full</literal></term>
              <listitem>
                <para>Resolve all conflicted files with copies of the
                files that were fetched from the server when you
                ran <command>svn update</command>.</para>
              </listitem>
            </varlistentry>

          </variablelist>

          <para>See <xref
            linkend="svn.tour.cycle.resolve"/> for an in-depth look at
            resolving conflicts.</para>

        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para>None</para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Working copy</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>No</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--accept ARG
--depth ARG
--quiet (-q)
--recursive (-R)
--targets FILENAME
</screen>
        </refsect1>
        
        <refsect1>
          <title>Examples</title>
          
          <para>Here's an example where, after a postponed conflict
            resolution during update, <command>svn resolve</command>
            replaces the all conflicts in
            file <filename>foo.c</filename> with your edits:</para>

          <screen>
$ svn up
Conflict discovered in 'foo.c'.
Select: (p) postpone, (df) diff-full, (e) edit,
        (h) help for more options: p
C    foo.c
Updated to revision 5.

$ svn resolve --accept mine-full foo.c
Resolved conflicted state of 'foo.c'
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.resolved">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>resolved</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn resolved</refname>
          <refpurpose><emphasis>Deprecated</emphasis>.
            Remove <quote>conflicted</quote> state on working copy
            files or directories.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn resolved PATH...</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>This command has been deprecated in favor of
            running <userinput>svn resolve --accept working <replaceable>PATH</replaceable></userinput>.
            See <xref linkend="svn.ref.svn.c.resolve"/> in the preceding section for
            details.</para>

          <para>Remove <quote>conflicted</quote> state on working copy
            files or directories.  This routine does not semantically
            resolve conflict markers; it merely removes
            conflict-related artifact files and allows
            <replaceable>PATH</replaceable> to be committed again;
            that is, it tells Subversion that the conflicts have been
            <quote>resolved.</quote>  See <xref
            linkend="svn.tour.cycle.resolve"/> for an in-depth look at
            resolving conflicts.</para> </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para>None</para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Working copy</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>No</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--depth ARG
--quiet (-q)
--recursive (-R)
--targets FILENAME
</screen>
        </refsect1>
        
        <refsect1>
          <title>Examples</title>
          
          <para>If you get a conflict on an update, your working
            copy will sprout three new files:</para>

          <screen>
$ svn update
C  foo.c
Updated to revision 31.
$ ls
foo.c
foo.c.mine
foo.c.r30
foo.c.r31
</screen>

          <para>Once you've resolved the conflict and
            <filename>foo.c</filename> is ready to be committed, run
            <command>svn resolved</command> to let your working copy
            know you've taken care of everything.</para>

          <warning>
            <para>You <emphasis>can</emphasis> just remove the
              conflict files and commit, but <command>svn
              resolved</command> fixes up some bookkeeping data
              in the working copy administrative area in addition
              to removing the conflict files, so we recommend that
              you use this command.</para>
          </warning>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.revert">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>revert</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn revert</refname>
          <refpurpose>Undo all local edits.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn revert PATH...</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Reverts any local changes to a file or directory and
            resolves any conflicted states.  <command>svn
            revert</command> will revert not only the contents of an
            item in your working copy, but also any property
            changes.  Finally, you can use it to undo any scheduling
            operations that you may have performed (e.g., files scheduled
            for addition or deletion can be
            <quote>unscheduled</quote>).</para>
        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para>None</para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Working copy</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>No</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--changelist ARG
--depth ARG
--quiet (-q)
--recursive (-R)
--targets FILENAME
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>Discard changes to a file:</para>

          <screen>
$ svn revert foo.c
Reverted foo.c
</screen>

          <para>If you want to revert a whole directory of files,
            use the <option>--depth=infinity</option> option:</para>

          <screen>
$ svn revert --depth=infinity .
Reverted newdir/afile
Reverted foo.c
Reverted bar.txt
</screen>

          <para>Lastly, you can undo any scheduling
            operations:</para>

          <screen>
$ svn add mistake.txt whoops
A         mistake.txt
A         whoops
A         whoops/oopsie.c

$ svn revert mistake.txt whoops
Reverted mistake.txt
Reverted whoops

$ svn status
?      mistake.txt
?      whoops
</screen>

          <warning>
            <para><command>svn revert</command> is inherently
              dangerous, since its entire purpose is to throw away
              data&mdash;namely, your uncommitted changes.  Once
              you've reverted, Subversion provides <emphasis>no
              way</emphasis> to get back those uncommitted
              changes.</para>

            <para>If you provide no targets to <command>svn
              revert</command>, it will do nothing&mdash;to protect
              you from accidentally losing changes in your working
              copy, <command>svn revert</command> requires you to
              provide at least one target.</para>
          </warning>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.status">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>status</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn status</refname>
          <refpurpose>Print the status of working copy files and directories.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn status [PATH...]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Print the status of working copy files and
            directories.  With no arguments, it prints only locally
            modified items (no repository access).  With
            <option>--show-updates</option>, it adds working revision
            and server out-of-date information.  With
            <option>--verbose</option>, it prints full revision
            information on every item.  With <option>--quiet</option>,
            it prints only summary information about locally modified
            items.</para>

          <para>The first six columns in the output are each one
            character wide, and each column gives you information
            about different aspects of each working copy item.</para>
          
          <para>The first column indicates that an item
            was added, deleted, or otherwise changed:</para>

          <variablelist>
            
            <varlistentry>
              <term><literal>' '</literal></term>
              <listitem>
                <para>No modifications.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>'A'</literal></term>
              <listitem>
                <para>Item is scheduled for addition.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>'D'</literal></term>
              <listitem>
                <para>Item is scheduled for deletion.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>'M'</literal></term>
              <listitem>
                <para>Item has been modified.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>'R'</literal></term>
              <listitem>
                <para>Item has been replaced in your working copy.
                This means the file was scheduled for deletion, and
                then a new file with the same name was scheduled for
                addition in its place.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>'C'</literal></term>
              <listitem>
                <para>The contents (as opposed to the properties) of
                  the item conflict with updates received from the
                  repository.</para>  
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>'X'</literal></term>
              <listitem>
                <para>Item is present because of an externals definition.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>'I'</literal></term>
              <listitem>
                <para>Item is being ignored (e.g., with the 
                  <literal>svn:ignore</literal> property).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>'?'</literal></term>
              <listitem>
                <para>Item is not under version control.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>'!'</literal></term>
              <listitem>
                <para>Item is missing (e.g., you moved or deleted it
                  without using <command>svn</command>).  This also
                  indicates that a directory is incomplete (a checkout
                  or update was interrupted).</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>'~'</literal></term>
              <listitem>
                <para>Item is versioned as one kind of object (file,
                  directory, link), but has been replaced by a different
                  kind of object.</para>
              </listitem>
            </varlistentry>

          </variablelist>

          <para>The second column tells the status of a file's or
            directory's properties:</para>

          <variablelist>
            
            <varlistentry>
              <term><literal>' '</literal></term>
              <listitem>
                <para>No modifications.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>'M'</literal></term>
              <listitem>
                <para>Properties for this item have been
                  modified.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>'C'</literal></term>
              <listitem>
                <para>Properties for this item are in conflict with
                  property updates received from the
                  repository.</para>
              </listitem>
            </varlistentry>

          </variablelist>

          <para>The third column is populated only if the
            working copy directory is locked (see
            <xref linkend="svn.tour.cleanup"/>):</para>

          <variablelist>
            
            <varlistentry>
              <term><literal>' '</literal></term>
              <listitem>
                <para>Item is not locked.</para>
              </listitem>
            </varlistentry>
            
            <varlistentry>
              <term><literal>'L'</literal></term>
              <listitem>
                <para>Item is locked.</para>
              </listitem>
            </varlistentry>

          </variablelist>

          <para>The fourth column is populated only if the item is
            scheduled for addition-with-history:</para>
          
          <variablelist>
            
            <varlistentry>
              <term><literal>' '</literal></term>
              <listitem>
                <para>No history scheduled with commit.</para>
              </listitem>
            </varlistentry>
            
            <varlistentry>
              <term><literal>'+'</literal></term>
              <listitem>
                <para>History scheduled with commit.</para>
              </listitem>
            </varlistentry>

          </variablelist>

          <para>The fifth column is populated only if the item is
            switched relative to its parent (see <xref
            linkend="svn.branchmerge.switchwc"/>):</para>

          <variablelist>
            
            <varlistentry>
              <term><literal>' '</literal></term>
              <listitem>
                <para>Item is a child of its parent directory.</para>
              </listitem>
            </varlistentry>
            
            <varlistentry>
              <term><literal>'S'</literal></term>
              <listitem>
                <para>Item is switched.</para>
              </listitem>
            </varlistentry>

          </variablelist>

          <para>The sixth column is populated with lock information:</para>
          
          <variablelist>
            
            <varlistentry>
              <term><literal>' '</literal></term>
              <listitem>
                <para>When <option>--show-updates</option> is used,
                the file is not locked.  If
                <option>--show-updates</option> is
                <emphasis>not</emphasis> used, this merely means that
                the file is not locked in this working copy.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>K</term>
              <listitem>
                <para>File is locked in this working copy.</para>
              </listitem>
            </varlistentry>
            
            <varlistentry>
              <term>O</term>
              <listitem>
                <para>File is locked either by another user or in
                another working copy.  This appears only when
                <option>--show-updates</option> is used.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>T</term>
              <listitem>
                <para>File was locked in this working copy, but the
                lock has been <quote>stolen</quote> and is invalid.
                The file is currently locked in the repository.  This
                appears only when <option>--show-updates</option> is
                used.</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term>B</term>
              <listitem>
                <para>File was locked in this working copy, but the
                lock has been <quote>broken</quote> and is invalid.
                The file is no longer locked.  This appears only when
                <option>--show-updates</option> is used.</para>
              </listitem>
            </varlistentry>

          </variablelist>




          <para>The out-of-date information appears in the seventh
            column (only if you pass the
            <option>--show-updates</option> option):</para>

          <variablelist>
            
            <varlistentry>
              <term><literal>' '</literal></term>
              <listitem>
                <para>The item in your working copy is up to date.</para>
              </listitem>
            </varlistentry>
            
            <varlistentry>
              <term><literal>'*'</literal></term>
              <listitem>
                <para>A newer revision of the item exists on the
                  server.</para>
              </listitem>
            </varlistentry>

          </variablelist>

          <para>The remaining fields are variable width and
            delimited by spaces.  The working revision is the next
            field if the <option>--show-updates</option> or
            <option>--verbose</option> option is passed.</para>
          
          <para>If the <option>--verbose</option> option is passed,
            the last committed revision and last committed author
            are displayed next.</para>
          
          <para>The working copy path is always the final field, so
            it can include spaces.</para>

        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para><command>stat</command>, <command>st</command></para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Nothing</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Only if using <option>--show-updates</option></para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--changelist ARG
--depth ARG
--ignore-externals
--incremental
--no-ignore
--quiet (-q)
--show-updates (-u)
--verbose (-v)
--xml
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>This is the easiest way to find out what changes you
            have made to your working copy:</para>

          <screen>
$ svn status wc
 M     wc/bar.c
A  +   wc/qax.c
</screen>

          <para>If you want to find out what files in your working
            copy are out of date, pass the
            <option>--show-updates</option> option (this will
            <emphasis>not</emphasis> make any changes to your
            working copy).  Here you can see that
            <filename>wc/foo.c</filename> has changed in the
            repository since we last updated our working
            copy:</para>

          <screen>
$ svn status --show-updates wc
 M           965    wc/bar.c
       *     965    wc/foo.c
A  +         965    wc/qax.c
Status against revision:    981
</screen>

          <note>
            <para><option>--show-updates</option>
              <emphasis>only</emphasis> places an asterisk next to
              items that are out of date (i.e., items that will be
              updated from the repository if you later use <command>svn
              update</command>).  <option>--show-updates</option> does
              <emphasis>not</emphasis> cause the status listing to
              reflect the repository's version of the item (although
              you can see the revision number in the repository by
              passing the <option>--verbose</option> option).</para>
          </note>

          <para>The most information you can get out of
            the status subcommand is as follows:</para>

          <screen>
$ svn status --show-updates --verbose wc
 M           965       938 sally        wc/bar.c
       *     965       922 harry        wc/foo.c
A  +         965       687 harry        wc/qax.c
             965       687 harry        wc/zig.c
Head revision:   981
</screen>

          <para>Lastly, you can get <command>svn status</command>
            output in XML format with the <option>--xml</option>
            option:</para>

          <screen>
$ svn status --xml wc
&lt;?xml version="1.0"?&gt;
&lt;status&gt;
&lt;target
   path="wc"&gt;
&lt;entry
   path="qax.c"&gt;
&lt;wc-status
   props="none"
   item="added"
   revision="0"&gt;
&lt;/wc-status&gt;
&lt;/entry&gt;
&lt;entry
   path="bar.c"&gt;
&lt;wc-status
   props="normal"
   item="modified"
   revision="965"&gt;
&lt;commit
   revision="965"&gt;
&lt;author&gt;sally&lt;/author&gt;
&lt;date&gt;2008-05-28T06:35:53.048870Z&lt;/date&gt;
&lt;/commit&gt;
&lt;/wc-status&gt;
&lt;/entry&gt;
&lt;/target&gt;
&lt;/status&gt;
</screen>

          <para>For many more examples of <command>svn status</command>,
            see <xref linkend="svn.tour.cycle.examine.status"/>.</para>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svn.c.switch">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>switch</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn switch</refname>
          <refpurpose>Update working copy to a different URL.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn switch URL[@PEGREV] [PATH]</programlisting>

          <programlisting>switch --relocate FROM TO [PATH...]</programlisting>


        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>The first variant of this subcommand (without the
            <option>--relocate</option> option) updates your working
            copy to point to a new URL&mdash;usually a URL that
            shares a common ancestor with your working copy, although
            not necessarily.  This is the Subversion way to move a
            working copy to a new branch.  If specified,
            <replaceable>PEGREV</replaceable> determines in which
            revision the target is first looked up.  See <xref
            linkend="svn.branchmerge.switchwc"/> for an in-depth look
            at switching.</para>

          <para>If <option>--force</option> is used, unversioned
            obstructing paths in the working copy do not automatically
            cause a failure if the switch attempts to add the same
            path.  If the obstructing path is the same type (file or
            directory) as the corresponding path in the repository, it
            becomes versioned but its contents are left untouched in
            the working copy.  This means that an obstructing
            directory's unversioned children may also obstruct and
            become versioned.  For files, any content differences
            between the obstruction and the repository are treated
            like a local modification to the working copy.  All
            properties from the repository are applied to the
            obstructing path.</para>

          <para>As with most subcommands, you can limit the scope of
            the switch operation to a particular tree depth using the
            <option>--depth</option> option.  Alternatively, you can
            use the <option>--set-depth</option> option to set a new
            <quote>sticky</quote> working copy depth on the switch
            target.  Currently, the depth of a working copy directory
            can only be increased (telescoped more deeply); you cannot
            make a directory more shallow.</para>

          <para>The <option>--relocate</option> option causes
            <command>svn switch</command> to do something different:
            it updates your working copy to point to <emphasis>the
            same</emphasis> repository directory, only at a different
            URL (typically because an administrator has moved the
            repository to another server, or to another URL on the
            same server).</para>

        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para><command>sw</command></para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Working copy</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Yes</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--accept ARG
--depth ARG
--diff3-cmd CMD
--force
--ignore-externals
--quiet (-q)
--relocate
--revision (-r) REV
--set-depth ARG
</screen>
        </refsect1>
        
        <refsect1>
          <title>Examples</title>

          <para>If you're currently inside the directory
            <filename>vendors</filename>, which was branched to
            <filename>vendors-with-fix</filename>, and you'd like to
            switch your working copy to that branch:</para>

          <screen>
$ svn switch http://svn.red-bean.com/repos/branches/vendors-with-fix .
U  myproj/foo.txt
U  myproj/bar.txt
U  myproj/baz.c
U  myproj/qux.c
Updated to revision 31.
</screen>

          <para>To switch back, just provide the URL to the
            location in the repository from which you originally
            checked out your working copy:</para>

          <screen>
$ svn switch http://svn.red-bean.com/repos/trunk/vendors .
U  myproj/foo.txt
U  myproj/bar.txt
U  myproj/baz.c
U  myproj/qux.c
Updated to revision 31.
</screen>

          <tip>
            <para>You can switch just part of your working copy to a
              branch if you don't want to switch your entire working
              copy.</para>
          </tip>

          <para>Sometimes an administrator might change the location
            (or apparent location) of your repository&mdash;in other
            words, the content of the repository doesn't change, but
            the repository's root URL does.  For example, the hostname
            may change, the URL scheme may change, or any part of the
            URL that leads to the repository itself may change.
            Rather than check out a new working copy, you can have the
            <command>svn switch</command> command
            <quote>rewrite</quote> your working copy's administrative
            metadata to refer to the new repository location.  If you
            use the <option>--relocate</option> option to <command>svn
            switch</command>, Subversion will contact the repository
            to validate the relocation request (looking for the
            repository at the new URL, of course), and then do this
            metadata rewriting.  No file contents will be changed as
            the result of this type of switch operation&mdash;this is
            a metadata-only modification to the working copy.</para>

          <screen>
$ svn checkout file:///var/svn/repos test
A  test/a
A  test/b
&hellip;

$ mv repos newlocation
$ cd test/

$ svn update
svn: Unable to open an ra_local session to URL
svn: Unable to open repository 'file:///var/svn/repos'

$ svn switch --relocate file:///var/svn/repos file:///tmp/newlocation .
$ svn update
At revision 3.
</screen>

          <warning>
            <para>Be careful when using the
            <option>--relocate</option> option.  If you mistype the
            argument, you might end up creating nonsensical URLs
            within your working copy that render the whole workspace
            unusable and tricky to fix.  It's also important to
            understand exactly when one should or shouldn't use
            <option>--relocate</option>.  Here's the rule of
            thumb:</para>
            
            <itemizedlist>
              <listitem><para>If the working copy needs to reflect a
                  new directory <emphasis>within</emphasis> the
                  repository, use just <command>svn
                  switch</command>.</para></listitem>

              <listitem><para>If the working copy still reflects the
                  same repository directory, but the location of the
                  repository itself has changed, use <command>svn
                  switch</command> with the <option>--relocate</option> option.</para></listitem>
            </itemizedlist>
          </warning>

        </refsect1>
      </refentry>


      <refentry id="svn.ref.svn.c.unlock">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>unlock</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn unlock</refname> 
            <refpurpose>Unlock working copy paths or URLs.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn unlock TARGET...</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Unlock each <replaceable>TARGET</replaceable>.  If any
            <replaceable>TARGET</replaceable> is locked by
            another user or no valid lock token exists in the working
            copy, print a warning and continue unlocking the rest of
            the <replaceable>TARGET</replaceable>s.  Use
            <option>--force</option> to break a lock belonging to
            another user or working copy.</para>

        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para>None</para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Working copy, repository</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Yes</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--force
--targets FILENAME
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>Unlock two files in your working copy:</para>

          <screen>
$ svn unlock tree.jpg house.jpg
'tree.jpg' unlocked.
'house.jpg' unlocked.
</screen>

          <para>Unlock a file in your working copy that is currently
            locked by another user:</para>

          <screen>
$ svn unlock tree.jpg
svn: 'tree.jpg' is not locked in this working copy
$ svn unlock --force tree.jpg
'tree.jpg' unlocked.
</screen>

          <para>Unlock a file without a working copy:</para>

          <screen>
$ svn unlock http://svn.red-bean.com/repos/test/tree.jpg
'tree.jpg unlocked.
</screen>

          <para>For further details, see <xref
            linkend="svn.advanced.locking"/>.</para>

        </refsect1>
      </refentry>


      <refentry id="svn.ref.svn.c.update">

        <indexterm>
          <primary>svn</primary>
          <secondary>subcommands</secondary>
          <tertiary>update</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svn update</refname>
          <refpurpose>Update your working copy.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svn update [PATH...]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para><command>svn update</command> brings changes from the
            repository into your working copy.  If no revision is given,
            it brings your working copy up to date with the
            <literal>HEAD</literal> revision.  Otherwise, it
            synchronizes the working copy to the revision given by the
            <option>--revision</option> option.  As part of the
            synchronization, <command>svn update</command> also
            removes any stale locks (see <xref
            linkend="svn.tour.cleanup"/>) found in the
            working copy.</para>

          <para>For each updated item, it prints a line that starts
            with a character reporting the action taken.  These
            characters have the following meaning:</para>

          <variablelist>

            <varlistentry>
              <term><literal>A</literal></term>
              <listitem>
                <para>Added</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>B</literal></term>
              <listitem>
                <para>Broken lock (third column only)</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>D</literal></term>
              <listitem>
                <para>Deleted</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>U</literal></term>
              <listitem>
                <para>Updated</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>C</literal></term>
              <listitem>
                <para>Conflicted</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>G</literal></term>
              <listitem>
                <para>Merged</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>E</literal></term>
              <listitem>
                <para>Existed</para>
              </listitem>
            </varlistentry>

          </variablelist>

          <para>A character in the first column signifies an update to
            the actual file, whereas updates to the file's properties
            are shown in the second column.  Lock information is
            printed in the third column.</para>

          <para>As with most subcommands, you can limit the scope of
            the update operation to a particular tree depth using the
            <option>--depth</option> option.  Alternatively, you can
            use the <option>--set-depth</option> option to set a new
            <quote>sticky</quote> working copy depth on the update
            target.  Currently, the depth of a working copy directory
            can only be increased (telescoped more deeply); you cannot
            make a directory more shallow.</para>
        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para><command>up</command></para>
        </refsect1>

        <refsect1>
          <title>Changes</title>
          <para>Working copy</para>
        </refsect1>

        <refsect1>
          <title>Accesses repository</title>
          <para>Yes</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--accept ARG
--changelist
--depth ARG
--diff3-cmd CMD
--editor-cmd ARG
--force
--ignore-externals
--quiet (-q)
--revision (-r) REV
--set-depth ARG
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>Pick up repository changes that have happened since
            your last update:</para>

          <screen>
$ svn update
A  newdir/toggle.c
A  newdir/disclose.c
A  newdir/launch.c
D  newdir/README
Updated to revision 32.
</screen>

          <para>You can also <quote>update</quote> your working copy
            to an older revision (Subversion doesn't have the concept
            of <quote>sticky</quote> files like CVS does; see <xref
            linkend="svn.forcvs"/>):</para>

          <screen>
$ svn update -r30
A  newdir/README
D  newdir/toggle.c
D  newdir/disclose.c
D  newdir/launch.c
U  foo.c
Updated to revision 30.
</screen>

          <tip>
            <para>If you want to examine an older revision of a
              single file, you may want to use <command>svn
              cat</command> instead&mdash;it won't change your working
              copy.</para>
          </tip>
          
        </refsect1>
      </refentry>
    </sect2>
    
  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.ref.svnadmin">
    <title>svnadmin</title>
    
    <para><command>svnadmin</command> is the administrative tool for
      monitoring and repairing your Subversion repository.  For
      detailed information on repository administration, see the maintenance section for <xref
      linkend="svn.reposadmin.maint.tk.svnadmin"/>.</para>

    <para>Since <command>svnadmin</command> works via direct repository access
      (and thus can only be used on the machine that holds the
      repository), it refers to the repository with a path, not a URL.</para>
      
    <!-- =============================================================== -->
    <sect2 id="svn.ref.svnadmin.sw">
      <title><command>svnadmin</command> Options</title> 
      
      <para>Options in <command>svmadin</command> are global, just
        as they are in <command>svn</command>:</para>

      <variablelist>
        
        <varlistentry>
          <term><option>--bdb-log-keep</option></term>
          <listitem>
            <para>(Berkeley DB-specific.) Disable automatic log removal
              of database logfiles.  Having these logfiles around
              can be convenient if you need to restore from a
              catastrophic repository failure.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--bdb-txn-nosync</option></term>
          <listitem>

            <para>(Berkeley DB-specific.) Disables fsync when
              committing database transactions.  Used with the
              <command>svnadmin create</command> command to create a
              Berkeley DB-backed repository with
              <literal>DB_TXN_NOSYNC</literal> enabled (which improves
              speed but has some risks associated with it).</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--bypass-hooks</option></term>
          <listitem>
            <para>Bypass the repository hook system.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--clean-logs</option></term>
          <listitem>
            <para>Remove unused Berkeley DB logs.</para>
          </listitem>
        </varlistentry>

        <!-- TODO config-dir?  Only 'svnadmin create' accepts it, and -->
        <!-- the underlying logic doesn't even use it.                -->

        <varlistentry>
          <term><option>--force-uuid</option></term>
          <listitem>
            <para>By default, when loading data into repository that
              already contains revisions, <command>svnadmin</command>
              will ignore the <literal>UUID</literal> from the dump
              stream.  This option will cause the repository's
              <literal>UUID</literal> to be set to the
              <literal>UUID</literal> from the stream.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--ignore-uuid</option></term>
          <listitem>
            <para>By default, when loading an empty repository,
              <command>svnadmin</command> will ignore the
              <literal>UUID</literal> from the dump stream.  This
              option will force that UUID to be ignored (useful for
              overriding your configuration file if it has
              <option>--force-uuid</option> set).</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--incremental</option></term>
          <listitem>
            <para>Dump a revision only as a diff against the
              previous revision, instead of the usual
              fulltext.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--parent-dir
          <replaceable>DIR</replaceable></option></term>
          <listitem>
            <para>When loading a dump file, root paths at
              <replaceable>DIR</replaceable> instead of
              <filename>/</filename>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--pre-1.4-compatible</option></term>
          <listitem>
            <para>When creating a new repository, use a format that is
            compatible with versions of Subversion earlier than
            Subversion 1.4.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--pre-1.5-compatible</option></term>
          <listitem>
            <para>When creating a new repository, use a format that is
            compatible with versions of Subversion earlier than
            Subversion 1.5.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--revision</option> (<option>-r</option>)
          <replaceable>ARG</replaceable></term>
          <listitem>
            <para>Specify a particular revision to operate
              on.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--quiet</option></term>
          <listitem>
            <para>Do not show normal progress&mdash;show only
              errors.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--use-post-commit-hook</option></term>
          <listitem>
            <para>When loading a dump file, runs the repository's
              <literal>post-commit</literal> hook after finalizing each newly loaded
              revision.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--use-post-revprop-change-hook</option></term>
          <listitem>
            <para>When changing a revision property, runs the
              repository's <literal>post-revprop-change</literal> hook after changing the
              revision property.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--use-pre-commit-hook</option></term>
          <listitem>
            <para>When loading a dump file, runs the repository's
              <literal>pre-commit</literal> hook before finalizing each newly loaded
              revision.  If the hook fails, aborts the commit and
              terminates the load process.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--use-pre-revprop-change-hook</option></term>
          <listitem>
            <para>When changing a revision property, runs the
              repository's <literal>pre-revprop-change</literal> hook before changing the
              revision property.  If the hook fails, aborts the
              modification and terminates.</para>
          </listitem>
        </varlistentry>

      </variablelist>
    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.ref.svnadmin.c">
      <title>svnadmin Subcommands</title>

      <para>Here are the various subcommands
        for the <command>svnadmin</command> program.</para>

      <refentry id="svn.ref.svnadmin.c.crashtest">

        <indexterm>
          <primary>svnadmin</primary>
          <secondary>subcommands</secondary>
          <tertiary>crashtest</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnadmin crashtest</refname>
          <refpurpose>Simulate a process that crashes.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnadmin crashtest REPOS_PATH</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

            <para>Open the repository at <replaceable>REPOS_PATH</replaceable>, then abort, thus
              simulating a process that crashes while holding an open
              repository handle.  This is used for testing automatic
              repository recovery (a new feature in Berkeley DB 4.4).
              It's unlikely that you'll need to run this
              command.</para>

          </refsect1>

        <refsect1>
          <title>Options</title>

          <para>None</para>

        </refsect1>

        <refsect1>
          <title>Examples</title>

          <screen>
$ svnadmin crashtest /var/svn/repos
Aborted
</screen>

          <para>Exciting, isn't it?</para>
          
        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnadmin.c.create">

        <indexterm>
          <primary>svnadmin</primary>
          <secondary>subcommands</secondary>
          <tertiary>create</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnadmin create</refname>
          <refpurpose>Create a new, empty repository.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnadmin create REPOS_PATH</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

            <para>Create a new, empty repository at the path provided.
              If the provided directory does not exist, it will be
              created for you.
              <footnote>
                <para>Remember, <command>svnadmin</command> works only
                  with local <emphasis>paths</emphasis>, not
                  <emphasis>URLs</emphasis>.</para>
              </footnote>
              As of Subversion 1.2, <command>svnadmin</command>
              creates new repositories with the
              <literal>FSFS</literal> filesystem backend by
              default.</para>

            <para>While <command>svnadmin create</command> will create
              the base directory for a new repository, it will not
              create intermediate directories.  For example, if you
              have an empty directory named
              <filename>/var/svn</filename>, creating
              <filename>/var/svn/repos</filename> will work, while
              attempting to create
              <filename>/var/svn/subdirectory/repos</filename> will
              fail with an error.</para>

          </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--bdb-log-keep
--bdb-txn-nosync
--config-dir DIR
--fs-type TYPE
--pre-1.4-compatible
--pre-1.5-compatible
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>Creating a new repository is this easy:</para>

          <screen>
$ svnadmin create /var/svn/repos
</screen>
          
          <para>In Subversion 1.0, a Berkeley DB repository is always
            created.  In Subversion 1.1, a Berkeley DB repository is
            the default repository type, but an FSFS repository can be
            created using the <option>--fs-type</option>
            option:</para>

          <screen>
$ svnadmin create /var/svn/repos --fs-type fsfs
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnadmin.c.deltify">

        <indexterm>
          <primary>svnadmin</primary>
          <secondary>subcommands</secondary>
          <tertiary>deltify</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnadmin deltify</refname>
          <refpurpose>Deltify changed paths in a revision range.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnadmin deltify [-r LOWER[:UPPER]] REPOS_PATH</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para><command>svnadmin deltify</command> exists in
            current versions of Subversion only for historical reasons.
            This command is deprecated and no longer needed.</para>

          <para>It dates from a time when Subversion offered
            administrators greater control over compression strategies
            in the repository.  This turned out to be a lot of
            complexity for <emphasis>very</emphasis> little gain, and
            this <quote>feature</quote> was deprecated.</para>

            </refsect1>
        <refsect1>
          <title>Options</title>
          
          <screen>
--quiet (-q)
--revision (-r) REV
</screen>
        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnadmin.c.dump">

        <indexterm>
          <primary>svnadmin</primary>
          <secondary>subcommands</secondary>
          <tertiary>dump</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnadmin dump</refname>
          <refpurpose>Dump the contents of the filesystem to <filename>stdout</filename>.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnadmin dump REPOS_PATH [-r LOWER[:UPPER]] [--incremental]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Dump the contents of the filesystem to <filename>stdout</filename> in a
            <quote>dump file</quote> portable format, sending feedback
            to <filename>stderr</filename>.  Dump revisions
            <replaceable>LOWER</replaceable> rev through
            <replaceable>UPPER</replaceable> rev.  If no revisions are
            given, dump all revision trees.  If only
            <replaceable>LOWER</replaceable> is given, dump that one
            revision tree.  See <xref linkend="svn.reposadmin.maint.migrate"/>
            for a practical use.</para>

          <para>By default, the Subversion dump stream contains a
            single revision (the first revision in the requested
            revision range) in which every file and directory in the
            repository in that revision is presented as though that whole
            tree was added at once, followed by other revisions (the
            remainder of the revisions in the requested range), which
            contain only the files and directories that were modified
            in those revisions.  For a modified file, the complete
            full-text representation of its contents, as well as all of
            its properties, are presented in the dump file; for a
            directory, all of its properties are presented.</para>

          <para>Two useful options modify the dump file
            generator's behavior.  The first is the
            <option>--incremental</option> option, which simply causes
            that first revision in the dump stream to contain only
            the files and directories modified in that revision,
            instead of being presented as the addition of a new tree,
            and in exactly the same way that every other revision in
            the dump file is presented.  This is useful for generating
            a relatively small dump file to be loaded into another
            repository that already has the files and directories
            that exist in the original repository.</para>

          <para>The second useful option is <option>--deltas</option>.
            This option causes <command>svnadmin dump</command> to,
            instead of emitting full-text representations of file
            contents and property lists, emit only deltas of those
            items against their previous versions.  This reduces (in
            some cases, drastically) the size of the dump file that
            <command>svnadmin dump</command> creates.  There are, however,
            disadvantages to using this option&mdash;deltified
            dump files are more CPU-intensive to create, cannot be
            operated on by <command>svndumpfilter</command>, and tend
            not to compress as well as their nondeltified counterparts
            when using third-party tools such as <command>gzip</command>
            and <command>bzip2</command>.</para>
        </refsect1>
        <refsect1>
          <title>Options</title>
          
          <screen>
--deltas
--incremental
--quiet (-q)
--revision (-r) REV
</screen>
        </refsect1>
        
        <refsect1>
          <title>Examples</title>

          <para>Dump your whole repository:</para>

          <screen>
$ svnadmin dump /var/svn/repos > full.dump
* Dumped revision 0.
* Dumped revision 1.
* Dumped revision 2.
&hellip;
</screen>

          <para>Incrementally dump a single transaction from your
            repository:</para>

          <screen>
$ svnadmin dump /var/svn/repos -r 21 --incremental > incr.dump
* Dumped revision 21.
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnadmin.c.help">

        <indexterm>
          <primary>svnadmin</primary>
          <secondary>subcommands</secondary>
          <tertiary>help</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnadmin help</refname> <refpurpose>Help!</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnadmin help [SUBCOMMAND...]</programlisting>
        </refsect1>

        <refsect1>
          <title>Description</title>

          <para>This subcommand is useful when you're trapped on a
            desert island with neither a Net connection nor a copy of
            this book.</para>
        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para><command>?</command>, <command>h</command></para>
        </refsect1>

      </refentry>

      <refentry id="svn.ref.svnadmin.c.hotcopy">

        <indexterm>
          <primary>svnadmin</primary>
          <secondary>subcommands</secondary>
          <tertiary>hotcopy</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnadmin hotcopy</refname>
          <refpurpose>Make a hot copy of a repository.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnadmin hotcopy REPOS_PATH NEW_REPOS_PATH</programlisting>
        </refsect1>

        <refsect1>
          <title>Description</title>

          <para>This subcommand makes a full <quote>hot</quote> backup
            of your repository, including all hooks, configuration
            files, and, of course, database files.  If you pass the
            <option>--clean-logs</option> option,
            <command>svnadmin</command> will perform a hot copy of your
            repository, and then remove unused Berkeley DB logs from
            the original repository.  You can run this command at any
            time and make a safe copy of the repository, regardless of
            whether other processes are using the repository.</para>

        </refsect1>

        <refsect1>
          <title>Options</title>
          
          <screen>
--clean-logs
</screen>

          <warning>
            <para>As described in <xref
              linkend="svn.reposadmin.basics.backends.bdb"/>, hot-copied
              Berkeley DB repositories are <emphasis>not</emphasis>
              portable across operating systems, nor will they work on
              machines with a different <quote>endianness</quote> than
              the machine where they were created.</para>
          </warning>

          </refsect1>

      </refentry>

      <refentry id="svn.ref.svnadmin.c.list-dblogs">

        <indexterm>
          <primary>svnadmin</primary>
          <secondary>subcommands</secondary>
          <tertiary>list-dblogs</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnadmin list-dblogs</refname>
          <refpurpose>Ask Berkeley DB which logfiles exist for a
            given Subversion repository (applies only to repositories
            using the <literal>bdb</literal> backend).</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnadmin list-dblogs REPOS_PATH</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Berkeley DB creates logs of all changes to the
            repository, which allow it to recover in the face of
            catastrophe.  Unless you enable
            <literal>DB_LOG_AUTOREMOVE</literal>, the logfiles
            accumulate, although most are no longer used and can be
            deleted to reclaim disk space.  See <xref
            linkend="svn.reposadmin.maint.diskspace"/> for more
            information.</para>
        </refsect1>

      </refentry>

      <refentry id="svn.ref.svnadmin.c.list-unused-dblogs">

        <indexterm>
          <primary>svnadmin</primary>
          <secondary>subcommands</secondary>
          <tertiary>list-unused-dblogs</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnadmin list-unused-dblogs</refname>
          <refpurpose>Ask Berkeley DB which logfiles can be safely
          deleted (applies only to repositories using the
          <literal>bdb</literal> backend).</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnadmin list-unused-dblogs REPOS_PATH</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Berkeley DB creates logs of all changes to the
            repository, which allow it to recover in the face of
            catastrophe.  Unless you enable
            <literal>DB_LOG_AUTOREMOVE</literal>, the logfiles
            accumulate, although most are no longer used and can be
            deleted to reclaim disk space.  See <xref
            linkend="svn.reposadmin.maint.diskspace"/> for more
            information.</para>
        </refsect1>

        <refsect1>
          <title>Examples</title>
          
          <para>Remove all unused logfiles from the repository:</para>

        <screen>
$ svnadmin list-unused-dblogs /var/svn/repos
/var/svn/repos/log.0000000031
/var/svn/repos/log.0000000032
/var/svn/repos/log.0000000033

$ svnadmin list-unused-dblogs /var/svn/repos | xargs rm
## disk space reclaimed!
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnadmin.c.load">

        <indexterm>
          <primary>svnadmin</primary>
          <secondary>subcommands</secondary>
          <tertiary>load</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnadmin load</refname> <refpurpose>Read a
            repository dump stream from
            <filename>stdin</filename>.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnadmin load REPOS_PATH</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Read a repository dump stream from
            <filename>stdin</filename>, committing new revisions into the repository's
            filesystem.  Send progress feedback to <filename>stdout</filename>.</para>
        </refsect1>

        <refsect1>
          <title>Options</title>
          
          <screen>
--force-uuid
--ignore-uuid
--parent-dir
--quiet (-q)
--use-post-commit-hook
--use-pre-commit-hook
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>This shows the beginning of loading a repository from
            a backup file (made, of course, with <command>svnadmin
            dump</command>):</para>

          <screen>
$ svnadmin load /var/svn/restored &lt; repos-backup
&lt;&lt;&lt; Started new txn, based on original revision 1
     * adding path : test ... done.
     * adding path : test/a ... done.
&hellip;
</screen>

          <para>Or if you want to load into a subdirectory:</para>

          <screen>
$ svnadmin load --parent-dir new/subdir/for/project \
                /var/svn/restored &lt; repos-backup
&lt;&lt;&lt; Started new txn, based on original revision 1
     * adding path : test ... done.
     * adding path : test/a ... done.
&hellip;
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnadmin.c.lslocks">

        <indexterm>
          <primary>svnadmin</primary>
          <secondary>subcommands</secondary>
          <tertiary>lslocks</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnadmin lslocks</refname> 
          <refpurpose>Print descriptions of all locks.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnadmin lslocks REPOS_PATH [PATH-IN-REPOS]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Print descriptions of all locks in
            repository <replaceable>REPOS_PATH</replaceable>
            underneath the
            path <replaceable>PATH-IN-REPOS</replaceable>.
            If <replaceable>PATH-IN-REPOS</replaceable> is not
            provided, it defaults to the root directory of the
            repository.</para>
        </refsect1>

        <refsect1>
          <title>Options</title>
          
          <para>None</para>
        </refsect1>

        <refsect1>
          <title>Examples</title>


          <para>This lists the one locked file in the repository at
            <filename>/var/svn/repos</filename>:</para>

          <screen>
$ svnadmin lslocks /var/svn/repos
Path: /tree.jpg
UUID Token: opaquelocktoken:ab00ddf0-6afb-0310-9cd0-dda813329753
Owner: harry
Created: 2005-07-08 17:27:36 -0500 (Fri, 08 Jul 2005)
Expires: 
Comment (1 line):
Rework the uppermost branches on the bald cypress in the foreground.
</screen>
        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnadmin.c.lstxns">

        <indexterm>
          <primary>svnadmin</primary>
          <secondary>subcommands</secondary>
          <tertiary>lstxns</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnadmin lstxns</refname>
          <refpurpose>Print the names of all uncommitted transactions.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnadmin lstxns REPOS_PATH</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Print the names of all uncommitted transactions.  See
            <xref linkend="svn.reposadmin.maint.diskspace.deadtxns" />
            for information on how uncommitted transactions are
            created and what you should do with them.</para>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>List all outstanding transactions in a
            repository:</para>

          <screen>
$ svnadmin lstxns /var/svn/repos/ 
1w
1x
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnadmin.c.recover">

        <indexterm>
          <primary>svnadmin</primary>
          <secondary>subcommands</secondary>
          <tertiary>recover</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnadmin recover</refname>

          <refpurpose>Bring a repository database back into a
          consistent state (applies only to repositories using the
          <literal>bdb</literal> backend).  In addition, if
          <filename>repos/conf/passwd</filename> does not exist, it
          will create a default passwordfile .</refpurpose>

        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnadmin recover REPOS_PATH</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Run this command if you get an error indicating that
            your repository needs to be recovered.</para>
        </refsect1>
        <refsect1>
          <title>Options</title>
          <screen>
--wait
</screen>
        </refsect1>
        <refsect1>
          <title>Examples</title>
          
          <para>Recover a hung repository:</para>

          <screen>
$ svnadmin recover /var/svn/repos/ 
Repository lock acquired.
Please wait; recovering the repository may take some time...

Recovery completed.
The latest repos revision is 34.
</screen>

          <para>Recovering the database requires an exclusive lock on
            the repository. (This is a <quote>database lock</quote>;
            see the sidebar <xref linkend="svn.advanced.locking.meanings"/>.)
            If another process is accessing the repository,
            then <command>svnadmin recover</command> will error:</para>
          <screen>
$ svnadmin recover /var/svn/repos
svn: Failed to get exclusive repository access; perhaps another process
such as httpd, svnserve or svn has it open?

$
</screen>

          <para>The <option>--wait</option> option, however, will
            cause <command>svnadmin recover</command> to wait
            indefinitely for other processes to disconnect:</para>

          <screen>
$ svnadmin recover /var/svn/repos --wait
Waiting on repository lock; perhaps another process has it open?

### time goes by&hellip;

Repository lock acquired.
Please wait; recovering the repository may take some time...

Recovery completed.
The latest repos revision is 34.
</screen>

        </refsect1>
      </refentry>


      <refentry id="svn.ref.svnadmin.c.rmlocks">

        <indexterm>
          <primary>svnadmin</primary>
          <secondary>subcommands</secondary>
          <tertiary>rmlocks</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnadmin rmlocks</refname>
          <refpurpose>Unconditionally remove one or more locks from a
          repository.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnadmin rmlocks REPOS_PATH LOCKED_PATH...</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Remove one or more locks from each <replaceable>LOCKED_PATH</replaceable>.</para>
        </refsect1>

        <refsect1>
          <title>Options</title>
          
          <para>None</para>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>This deletes the locks on
            <filename>tree.jpg</filename> and
            <filename>house.jpg</filename> in the repository at
            <filename>/var/svn/repos</filename>:</para>

          <screen>
$ svnadmin rmlocks /var/svn/repos tree.jpg house.jpg
Removed lock on '/tree.jpg.
Removed lock on '/house.jpg.
</screen>
        </refsect1>
      </refentry>


      <refentry id="svn.ref.svnadmin.c.rmtxns">

        <indexterm>
          <primary>svnadmin</primary>
          <secondary>subcommands</secondary>
          <tertiary>rmtxns</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnadmin rmtxns</refname>
          <refpurpose>Delete transactions from a repository.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnadmin rmtxns REPOS_PATH TXN_NAME...</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Delete outstanding transactions from a repository.
            This is covered in detail in <xref
            linkend="svn.reposadmin.maint.diskspace.deadtxns" />.</para>
        </refsect1>

        <refsect1>
          <title>Options</title>
          
          <screen>
--quiet (-q)
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>Remove named transactions:</para>

          <screen>
$ svnadmin rmtxns /var/svn/repos/ 1w 1x
</screen>

          <para>Fortunately, the output of <command>lstxns</command>
            works great as the input for <command>rmtxns</command>:</para>

          <screen>
$ svnadmin rmtxns /var/svn/repos/  `svnadmin lstxns /var/svn/repos/`
</screen>

          <para>This removes all uncommitted transactions from
            your repository.</para>

        </refsect1>
      </refentry>


      <refentry id="svn.ref.svnadmin.c.setlog">

        <indexterm>
          <primary>svnadmin</primary>
          <secondary>subcommands</secondary>
          <tertiary>setlog</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnadmin setlog</refname>
          <refpurpose>Set the log message on a revision.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnadmin setlog REPOS_PATH -r REVISION FILE</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Set the log message on
            revision <replaceable>REVISION</replaceable> to the
            contents of <replaceable>FILE</replaceable>.</para>

          <para>This is similar to using <command>svn propset</command>
            with the <option>--revprop</option> option to set the <literal>svn:log</literal> property
            on a revision, except that you can also use the option
            <option>--bypass-hooks</option> to avoid running any pre-
            or post-commit hooks, which is useful if the modification
            of revision properties has not been enabled in
            the <literal>pre-revprop-change</literal> hook.</para>

          <warning>
            <para>Revision properties are not under version control,
              so this command will permanently overwrite the previous
              log message.</para>
          </warning>

        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--bypass-hooks
--revision (-r) REV
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>Set the log message for revision 19 to the contents of
            the file <filename>msg</filename>:</para>

          <screen>
$ svnadmin setlog /var/svn/repos/ -r 19 msg
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnadmin.c.setrevprop">

        <indexterm>
          <primary>svnadmin</primary>
          <secondary>subcommands</secondary>
          <tertiary>setrevprop</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnadmin setrevprop</refname>
          <refpurpose>Set a property on a revision.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnadmin setrevprop REPOS_PATH -r REVISION NAME FILE</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

            <para>Set the property <replaceable>NAME</replaceable> on
              revision <replaceable>REVISION</replaceable> to the
              contents of <replaceable>FILE</replaceable>. Use
              <option>--use-pre-revprop-change-hook</option>
              or <option>--use-post-revprop-change-hook</option> to
              trigger the revision property-related hooks (e.g., if
              you want an email notification sent from your <literal>post-revprop-change-hook</literal>).</para>

          </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--revision (-r) ARG
--use-post-revprop-change-hook
--use-pre-revprop-change-hook
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>The following sets the revision
          property <literal>repository-photo</literal> to the contents
          of the file <filename>sandwich.png</filename>:</para>

          <screen>
$svnadmin setrevprop /var/svn/repos -r 0 repository-photo sandwich.png
</screen>

          <para>As you can see, <command>svnadmin setrevprop</command>
            has no output upon success.</para>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnadmin.c.setuuid">

        <indexterm>
          <primary>svnadmin</primary>
          <secondary>subcommands</secondary>
          <tertiary>setuuid</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnadmin setuuid</refname>
          <refpurpose>Reset the repository UUID.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnadmin setuuid REPOS_PATH [NEW_UUID]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

            <para>Reset the repository UUID for the repository located
              at <replaceable>REPOS_PATH</replaceable>.
              If <replaceable>NEW_UUID</replaceable> is provided, use
              that as the new repository UUID; otherwise, generate a
              brand-new UUID for the repository.</para>

          </refsect1>

        <refsect1>
          <title>Options</title>

          <para>None</para>

        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>If you've <command>svnsync</command>ed <filename>/var/svn/repos</filename>
            to <filename>/var/svn/repos-new</filename> and intend to use <filename>repos-new</filename> as your
            canonical repository, you may want to change the UUID for
            <filename>repos-new</filename> to the UUID of <filename>repos</filename> so that your users don't
            have to check out a new working copy to accommodate the
            change:</para>

          <screen>
$ svnadmin setuuid /var/svn/repos-new 2109a8dd-854f-0410-ad31-d604008985ab
</screen>

          <para>As you can see, <command>svnadmin setuuid</command>
            has no output upon success.</para>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnadmin.c.upgrade">

        <indexterm>
          <primary>svnadmin</primary>
          <secondary>subcommands</secondary>
          <tertiary>upgrade</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnadmin upgrade</refname>
          <refpurpose>Upgrade a repository to the latest supported
            schema version.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnadmin upgrade REPOS_PATH</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

            <para>Upgrade the repository located
              at <replaceable>REPOS_PATH</replaceable> to the latest
              supported schema version.</para>

            <para>This functionality is provided as a convenience for
              repository administrators who wish to make use of new
              Subversion functionality without having to undertake a
              potentially costly full repository dump and load
              operation.  As such, the upgrade performs only the
              minimum amount of work needed to accomplish this while
              still maintaining the integrity of the repository.
              While a dump and subsequent load guarantee the most
              optimized repository state, <command>svnadmin
              upgrade</command> does not.</para>

            <warning>
              <para>You should <emphasis>always</emphasis> back up your
                repository before upgrading.</para>
            </warning>

          </refsect1>

        <refsect1>
          <title>Options</title>

          <para>None</para>

        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>Upgrade the repository at
            path <filename>/var/repos/svn</filename>:</para>

          <screen>
$ svnadmin upgrade /var/repos/svn
Repository lock acquired.
Please wait; upgrading the repository may take some time...

Upgrade completed.
</screen>
          
        </refsect1>
      </refentry>

      <!-- this could use a lot more explanation.  When should I use
      it?  What do I do if it fails? -->
      <refentry id="svn.ref.svnadmin.c.verify">

        <indexterm>
          <primary>svnadmin</primary>
          <secondary>subcommands</secondary>
          <tertiary>verify</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnadmin verify</refname>
          <refpurpose>Verify the data stored in the repository.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnadmin verify REPOS_PATH</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Run this command if you wish to verify the integrity
            of your repository.  This basically iterates through all
            revisions in the repository by internally dumping all
            revisions and discarding the output&mdash;it's a good idea
            to run this on a regular basis to guard against latent
            hard disk failures and <quote>bitrot.</quote>  If this
            command fails&mdash;which it will do at the first sign of
            a problem&mdash;that means your repository has at
            least one corrupted revision, and you should restore the
            corrupted revision from a backup (you did make a backup,
            didn't you?).</para>

        </refsect1>
        
        <refsect1>
          <title>Options</title>

          <screen>
--quiet (-q)
--revision (-r) ARG
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>
          
          <para>Verify a hung repository:</para>

          <screen>
$ svnadmin verify /var/svn/repos/ 
* Verified revision 1729.
</screen>

        </refsect1>
      </refentry>

    </sect2>

  </sect1>
  
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.ref.svnlook">
    <title>svnlook</title>
    
    <para><command>svnlook</command> is a command-line utility for
      examining different aspects of a Subversion repository.  It
      does not make any changes to the repository&mdash;it's just
      used for <quote>peeking.</quote>
      <command>svnlook</command> is typically used by the
      repository hooks, but a repository administrator might find it
      useful for diagnostic purposes.</para>

    <para>Since <command>svnlook</command> works via direct repository access
      (and thus can be used only on the machine that holds the
      repository), it refers to the repository with a path, not a URL.</para>

    <para>If no revision or transaction is specified,
      <command>svnlook</command> defaults to the youngest (most
      recent) revision of the repository.</para>
    
    <!-- =============================================================== -->
    <sect2 id="svn.ref.svnlook.sw">
      <title>svnlook Options</title>
      
      <para>Options in <command>svnlook</command> are global, just
        as they are in <command>svn</command> and
        <command>svnadmin</command>; however, most options apply
        to only one subcommand since the functionality of
        <command>svnlook</command> is (intentionally) limited in
        scope:</para>

      <variablelist>

        <varlistentry>
          <term><option>--copy-info</option></term>
          <listitem>
            <para>Causes <command>svnlook changed</command> to show
              detailed copy source information.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--no-diff-deleted</option></term>
          <listitem>
            <para>Prevents <command>svnlook diff</command> from printing
              differences for deleted files.  The default behavior
              when a file is deleted in a transaction/revision is
              to print the same differences that you would see if
              you had left the file but removed all the content.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--no-diff-added</option></term>
        <listitem>
          <para>Prevents <command>svnlook diff</command> from printing
            differences for added files.  The default behavior when
            you add a file is to print the same differences that you
            would see if you had added the entire contents of an
            existing (empty) file.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--revision</option>
            (<option>-r</option>)</term>
          <listitem>
            <para>Specifies a particular revision number that you wish
              to examine.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--revprop</option></term>
          <listitem>
            <para>Operates on a revision property instead of a
              property specific to a file or directory.  This option
              requires that you also pass a revision with the
              <option>--revision</option> (<option>-r</option>)
              option.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--transaction</option>
            (<option>-t</option>)</term>
          <listitem>
            <para>Specifies a particular transaction ID that you wish to
              examine.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--show-ids</option></term>
          <listitem>
            <para>Shows the filesystem node revision IDs for each path in the filesystem
              tree.</para>
          </listitem>
        </varlistentry>

      </variablelist>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.ref.svnlook.c">
      <title>svnlook Subcommands</title>

      <para>Here are the various subcommands
        for the <command>svnlook</command> program.</para>

      <refentry id="svn.ref.svnlook.c.author">

        <indexterm>
          <primary>svnlook</primary>
          <secondary>subcommands</secondary>
          <tertiary>author</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnlook author</refname>
          <refpurpose>Print the author.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnlook author REPOS_PATH</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Print the author of a revision or transaction in
            the repository.</para>
        </refsect1>

        <refsect1>
          <title>Options</title>
          
          <screen>
--revision (-r) REV
--transaction (-t) TXN
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

        <para><command>svnlook author</command> is handy, but not
          very exciting:</para>

          <screen>
$ svnlook author -r 40 /var/svn/repos 
sally
</screen>            

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnlook.c.cat">

        <indexterm>
          <primary>svnlook</primary>
          <secondary>subcommands</secondary>
          <tertiary>cat</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnlook cat</refname>
          <refpurpose>Print the contents of a file.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnlook cat REPOS_PATH PATH_IN_REPOS</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Print the contents of a file.</para>

          </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--revision (-r) REV
--transaction (-t) TXN
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>This shows the contents of a file in transaction
            <literal>ax8</literal>, located at 
            <filename>/trunk/README</filename>:</para>

          <screen>
$ svnlook cat -t ax8 /var/svn/repos /trunk/README

               Subversion, a version control system.
               =====================================

$LastChangedDate: 2003-07-17 10:45:25 -0500 (Thu, 17 Jul 2003) $

Contents:

     I. A FEW POINTERS
    II. DOCUMENTATION
   III. PARTICIPATING IN THE SUBVERSION COMMUNITY
&hellip;
</screen>
          
        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnlook.c.changed">

        <indexterm>
          <primary>svnlook</primary>
          <secondary>subcommands</secondary>
          <tertiary>changed</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnlook changed</refname>
          <refpurpose>Print the paths that were changed.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnlook changed REPOS_PATH</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Print the paths that were changed in a particular
            revision or transaction, as well as <quote>svn
            update-style</quote> status letters in the first two
            columns:</para>

          <variablelist>
            
            <varlistentry>
              <term><literal>'A '</literal></term>
              <listitem>
                <para>Item added to repository</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>'D '</literal></term>
              <listitem>
                <para>Item deleted from repository</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>'U '</literal></term>
              <listitem>
                <para>File contents changed</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>'_U'</literal></term>
              <listitem>
                <para>Properties of item changed; note the leading underscore</para>
              </listitem>
            </varlistentry>

            <varlistentry>
              <term><literal>'UU'</literal></term>
              <listitem>
                <para>File contents and properties changed</para>
              </listitem>
            </varlistentry>

          </variablelist>

          <para>Files and directories can be distinguished, as
            directory paths are displayed with a
            trailing <quote><literal>/</literal></quote>
            character.</para>

        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--copy-info
--revision (-r) REV
--transaction (-t) TXN
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>This shows a list of all the changed files and
            directories in revision 39 of a test repository.  Note
            that the first changed item is a directory, as evidenced
            by the trailing <literal>/</literal>:</para>

          <screen>
$ svnlook changed -r 39 /var/svn/repos
A   trunk/vendors/deli/
A   trunk/vendors/deli/chips.txt
A   trunk/vendors/deli/sandwich.txt
A   trunk/vendors/deli/pickle.txt
U   trunk/vendors/baker/bagel.txt
_U  trunk/vendors/baker/croissant.txt
UU  trunk/vendors/baker/pretzel.txt
D   trunk/vendors/baker/baguette.txt
</screen>

          <para>Here's an example that shows a revision in which a
            file was renamed:</para>

          <screen>
$ svnlook changed -r 64 /var/svn/repos
A   trunk/vendors/baker/toast.txt
D   trunk/vendors/baker/bread.txt
</screen>

          <para>Unfortunately, nothing in the preceding output reveals
            the connection between the deleted and added files.  Use
            the <option>--copy-info</option> option to make this
            relationship more apparent:</para>

          <screen>
$ svnlook changed -r 64 --copy-info /var/svn/repos
A + trunk/vendors/baker/toast.txt
    (from trunk/vendors/baker/bread.txt:r63)
D   trunk/vendors/baker/bread.txt
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnlook.c.date">

        <indexterm>
          <primary>svnlook</primary>
          <secondary>subcommands</secondary>
          <tertiary>date</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnlook date</refname>
          <refpurpose>Print the datestamp.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnlook date REPOS_PATH</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Print the datestamp of a revision or transaction in
            a repository.</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--revision (-r) REV
--transaction (-t) TXN
</screen>
        </refsect1>
        
        <refsect1>
          <title>Examples</title>
          
          <para>This shows the date of revision 40 of a test
            repository:</para>

          <screen>
$ svnlook date -r 40 /var/svn/repos/
2003-02-22 17:44:49 -0600 (Sat, 22 Feb 2003)
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnlook.c.diff">

        <indexterm>
          <primary>svnlook</primary>
          <secondary>subcommands</secondary>
          <tertiary>diff</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnlook diff</refname>
          <refpurpose>Print differences of changed files and properties.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnlook diff REPOS_PATH</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Print GNU-style differences of changed files and
            properties in a repository.</para>
        </refsect1>

        <refsect1>
          <title>Options</title>
          
          <screen>
--diff-copy-from
--no-diff-added
--no-diff-deleted
--revision (-r) REV
--transaction (-t) TXN
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>
          
          <para>This shows a newly added (empty) file, a deleted
            file, and a copied file:</para>

          <screen>
$ svnlook diff -r 40 /var/svn/repos/
Copied: egg.txt (from rev 39, trunk/vendors/deli/pickle.txt)

Added: trunk/vendors/deli/soda.txt
==============================================================================

Modified: trunk/vendors/deli/sandwich.txt
==============================================================================
--- trunk/vendors/deli/sandwich.txt	(original)
+++ trunk/vendors/deli/sandwich.txt	2003-02-22 17:45:04.000000000 -0600
@@ -0,0 +1 @@
+Don't forget the mayo!

Modified: trunk/vendors/deli/logo.jpg
==============================================================================
(Binary files differ)

Deleted: trunk/vendors/deli/chips.txt
==============================================================================

Deleted: trunk/vendors/deli/pickle.txt
==============================================================================
</screen>
          
          <para>If a file has a nontextual
            <literal>svn:mime-type</literal> property, the
            differences are not explicitly shown.</para>
        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnlook.c.dirs-changed">

        <indexterm>
          <primary>svnlook</primary>
          <secondary>subcommands</secondary>
          <tertiary>dirs-changed</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnlook dirs-changed</refname>
          <refpurpose>Print the directories that were themselves changed.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnlook dirs-changed REPOS_PATH</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Print the directories that were themselves changed
            (property edits) or whose file children were
            changed.</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--revision (-r) REV
--transaction (-t) TXN
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>This shows the directories that changed in
            revision 40 in our sample repository:</para>

          <screen>
$ svnlook dirs-changed -r 40 /var/svn/repos
trunk/vendors/deli/
</screen>
          
        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnlook.c.help">

        <indexterm>
          <primary>svnlook</primary>
          <secondary>subcommands</secondary>
          <tertiary>help</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnlook help</refname> <refpurpose>Help!</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>Also svnlook -h and svnlook -?.</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Displays the help message
            for <command>svnlook</command>.  This command, like its
            brother, <command>svn help</command>, is also your friend,
            even though you never call it anymore and forgot to invite
            it to your last party.</para>
        </refsect1>

        <refsect1>
          <title>Options</title>
          <para>None</para>
        </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para><command>?</command>, <command>h</command></para>
        </refsect1>

      </refentry>

      <refentry id="svn.ref.svnlook.c.history">

        <indexterm>
          <primary>svnlook</primary>
          <secondary>subcommands</secondary>
          <tertiary>history</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnlook history</refname>
          <refpurpose>Print information about the history of a path in
            the repository (or the root directory if no path is
            supplied).</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnlook history REPOS_PATH [PATH_IN_REPOS]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Print information about the history of a path in
            the repository (or the root directory if no path is
            supplied).</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--limit (-l) ARG
--revision (-r) REV
--show-ids
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>This shows the history output for the path
            <filename>/branches/bookstore</filename> as of revision 13 in our
            sample repository:</para>

          <screen>
$ svnlook history -r 13 /var/svn/repos /branches/bookstore --show-ids
REVISION   PATH &lt;ID&gt;
--------   ---------
      13   /branches/bookstore &lt;1.1.r13/390&gt;
      12   /branches/bookstore &lt;1.1.r12/413&gt;
      11   /branches/bookstore &lt;1.1.r11/0&gt;
       9   /trunk &lt;1.0.r9/551&gt;
       8   /trunk &lt;1.0.r8/131357096&gt;
       7   /trunk &lt;1.0.r7/294&gt;
       6   /trunk &lt;1.0.r6/353&gt;
       5   /trunk &lt;1.0.r5/349&gt;
       4   /trunk &lt;1.0.r4/332&gt;
       3   /trunk &lt;1.0.r3/335&gt;
       2   /trunk &lt;1.0.r2/295&gt;
       1   /trunk &lt;1.0.r1/532&gt;
</screen>
          
        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnlook.c.info">

        <indexterm>
          <primary>svnlook</primary>
          <secondary>subcommands</secondary>
          <tertiary>info</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnlook info</refname>
          <refpurpose>Print the author, datestamp, log message size,
            and log message.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnlook info REPOS_PATH</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Print the author, datestamp, log message size (in bytes),
            and log message, followed by a newline character.</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--revision (-r) REV
--transaction (-t) TXN
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>This shows the info output for revision 40 in our
            sample repository:</para>

          <screen>
$ svnlook info -r 40 /var/svn/repos
sally
2003-02-22 17:44:49 -0600 (Sat, 22 Feb 2003)
16
Rearrange lunch.
</screen>
          
        </refsect1>
      </refentry>


      <refentry id="svn.ref.svnlook.c.lock">

        <indexterm>
          <primary>svnlook</primary>
          <secondary>subcommands</secondary>
          <tertiary>lock</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnlook lock</refname>
          <refpurpose>If a lock exists on a path in the repository,
            describe it.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnlook lock REPOS_PATH PATH_IN_REPOS</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Print all information available for the lock at
              <replaceable>PATH_IN_REPOS</replaceable>.  If
              <replaceable>PATH_IN_REPOS</replaceable> is not locked,
              print nothing.</para>
        </refsect1>

        <refsect1>
          <title>Options</title>
            
          <para>None</para>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>This describes the lock on the file
            <filename>tree.jpg</filename>:</para>

          <screen>
$ svnlook lock /var/svn/repos tree.jpg
UUID Token: opaquelocktoken:ab00ddf0-6afb-0310-9cd0-dda813329753
Owner: harry
Created: 2005-07-08 17:27:36 -0500 (Fri, 08 Jul 2005)
Expires: 
Comment (1 line):
Rework the uppermost branches on the bald cypress in the foreground.
</screen>
          
        </refsect1>
      </refentry>


      <refentry id="svn.ref.svnlook.c.log">

        <indexterm>
          <primary>svnlook</primary>
          <secondary>subcommands</secondary>
          <tertiary>log</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnlook log</refname>
          <refpurpose>Print the log message, followed by a newline 
            character.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnlook log REPOS_PATH</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Print the log message.</para>
        </refsect1>

        <refsect1>
          <title>Options</title>
          
          <screen>
--revision (-r) REV
--transaction (-t) TXN
</screen>
        </refsect1>
        
        <refsect1>
          <title>Examples</title>
          
          <para>This shows the log output for revision 40 in our sample
            repository:</para>

          <screen>
$ svnlook log /var/svn/repos/
Rearrange lunch.
</screen>
          
        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnlook.c.propget">

        <indexterm>
          <primary>svnlook</primary>
          <secondary>subcommands</secondary>
          <tertiary>propget</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnlook propget</refname>
          <refpurpose>Print the raw value of a property on a path in
            the repository.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnlook propget REPOS_PATH PROPNAME [PATH_IN_REPOS]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>List the value of a property on a path in the
            repository.</para>

          </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para><command>pg</command>, <command>pget</command></para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--revision (-r) REV
--revprop
--transaction (-t) TXN
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>This shows the value of the <quote>seasonings</quote> property
            on the file <filename>/trunk/sandwich</filename> in the
            <literal>HEAD</literal> revision:</para>

          <screen>
$ svnlook pg /var/svn/repos seasonings /trunk/sandwich
mustard
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnlook.c.proplist">

        <indexterm>
          <primary>svnlook</primary>
          <secondary>subcommands</secondary>
          <tertiary>proplist</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnlook proplist</refname>
          <refpurpose>Print the names and values of versioned file and
            directory properties.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnlook proplist REPOS_PATH [PATH_IN_REPOS]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>List the properties of a path in the repository.  With
            <option>--verbose</option>, show the property values too.</para>

          </refsect1>

        <refsect1>
          <title>Alternate names</title>
          <para><command>pl</command>, <command>plist</command></para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--revision (-r) REV
--revprop
--transaction (-t) TXN
--verbose (-v)
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>This shows the names of properties set on the file
            <filename>/trunk/README</filename> in the
            <literal>HEAD</literal> revision:</para>

          <screen>
$ svnlook proplist /var/svn/repos /trunk/README
  original-author
  svn:mime-type
</screen>

          <para>This is the same command as in the preceding example,
            but this time showing the property values as well:</para>

          <screen>
$ svnlook --verbose proplist /var/svn/repos /trunk/README
  original-author : harry
  svn:mime-type : text/plain
</screen>
          
        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnlook.c.tree">
        <indexterm>
          <primary>svnlook</primary>
          <secondary>subcommands</secondary>
          <tertiary>tree</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnlook tree</refname>
          <refpurpose>Print the tree.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnlook tree REPOS_PATH [PATH_IN_REPOS]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>
          <para>Print the tree, starting at
            <replaceable>PATH_IN_REPOS</replaceable> (if supplied; at
            the root of the tree otherwise), optionally showing node
            revision IDs.</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--full-paths
--non-recursive (-N)
--revision (-r) REV
--show-ids
--transaction (-t) TXN
</screen>
        </refsect1>

        <refsect1>
          <title>Example</title>
          
          <para>This shows the tree output (with nodeIDs) for revision
            13 in our sample repository:</para>

          <screen>
$ svnlook tree -r 13 /var/svn/repos --show-ids
/ &lt;0.0.r13/811&gt;
 trunk/ &lt;1.0.r9/551&gt;
  button.c &lt;2.0.r9/238&gt;
  Makefile &lt;3.0.r7/41&gt;
  integer.c &lt;4.0.r6/98&gt;
 branches/ &lt;5.0.r13/593&gt;
  bookstore/ &lt;1.1.r13/390&gt;
   button.c &lt;2.1.r12/85&gt;
   Makefile &lt;3.0.r7/41&gt;
   integer.c &lt;4.1.r13/109&gt;
</screen>
          
        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnlook.c.uuid">

        <indexterm>
          <primary>svnlook</primary>
          <secondary>subcommands</secondary>
          <tertiary>uuid</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnlook uuid</refname>
          <refpurpose>Print the repository's
          <literal>UUID</literal>.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnlook uuid REPOS_PATH</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Print the <literal>UUID</literal> for the repository.
            The <literal>UUID</literal> is the repository's
            <emphasis>u</emphasis>niversal <emphasis>u</emphasis>nique
            <emphasis>id</emphasis>entifier.  The Subversion client
            uses this identifier to differentiate between one
            repository and another.</para>
        </refsect1>

        <refsect1>
          <title>Options</title>
          <para>None</para>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <screen>
$ svnlook uuid /var/svn/repos
e7fe1b91-8cd5-0310-98dd-2f12e793c5e8
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnlook.c.youngest">

        <indexterm>
          <primary>svnlook</primary>
          <secondary>subcommands</secondary>
          <tertiary>youngest</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnlook youngest</refname>
          <refpurpose>Print the youngest revision number.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnlook youngest REPOS_PATH</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Print the youngest revision number of a repository.</para>
        </refsect1>

        <refsect1>
          <title>Options</title>
          <para>None</para>
        </refsect1>

        <refsect1>
          <title>Examples</title>

        <para>This shows the youngest revision of our sample
          repository:</para>

          <screen>
$ svnlook youngest /var/svn/repos/ 
42
</screen>

        </refsect1>
      </refentry>

    </sect2>
  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.ref.svnsync">

    <title>svnsync</title>
    
    <para><command>svnsync</command> is the Subversion remote
      repository mirroring tool.  Put simply, it allows you to replay
      the revisions of one repository into another one.</para>

    <para>In any mirroring scenario, there are two repositories: the
      source repository, and the mirror (or <quote>sink</quote>)
      repository.  The source repository is the repository from which
      <command>svnsync</command> pulls revisions.  The mirror
      repository is the destination for the revisions pulled from the
      source repository.  Each of the repositories may be local or
      remote&mdash;they are only ever addressed by their URLs.</para>

    <para>The <command>svnsync</command> process requires only read
      access to the source repository; it never attempts to modify it.
      But obviously, <command>svnsync</command> requires both read and
      write access to the mirror repository.</para>

    <warning>
      <para><command>svnsync</command> is very sensitive to changes
        made in the mirror repository that weren't made as part of a
        mirroring operation.  To prevent this from happening, it's
        best if the <command>svnsync</command> process is the only
        process permitted to modify the mirror repository.</para>
    </warning>

    <!-- =============================================================== -->
    <sect2 id="svn.ref.svnsync.sw">
      <title>svnsync Options</title>

      <para>Options in <command>svnsync</command> are global, just
        as they are in <command>svn</command> and
        <command>svnadmin</command>:</para>

      <variablelist>

        <varlistentry>
          <term><option>--config-dir</option>
            <replaceable>DIR</replaceable></term>
          <listitem>
            <para>Instructs Subversion to read configuration
              information from the specified directory instead of the
              default location (<filename>.subversion</filename> in
              the user's home directory).</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--no-auth-cache</option></term>
          <listitem>
            <para>Prevents caching of authentication information
              (e.g., username and password) in the Subversion
              runtime configuration directories.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--non-interactive</option></term>
          <listitem>
            <para>In the case of an authentication failure or
              insufficient credentials, prevents prompting for
              credentials (e.g., username or password).  This is useful
              if you're running Subversion inside an automated
              script and it's more appropriate to have Subversion fail
              than to prompt for more information.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--quiet</option> (<option>-q</option>)</term>
          <listitem>
            <para>Requests that the client print only essential
              information while performing an operation.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--source-password</option>
            <replaceable>PASSWD</replaceable></term>
          <listitem>
            <para>Specifies the password for the Subversion server
              from which you are syncing.  If not provided, or if
              incorrect, Subversion will prompt you for this
              information as needed.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--source-username</option>
            <replaceable>NAME</replaceable></term>
          <listitem>
            <para>Specifies the username for the Subversion server
              from which you are syncing.  If not provided, or if
              incorrect, Subversion will prompt you for this
              information as needed.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--sync-password</option>
            <replaceable>PASSWD</replaceable></term>
          <listitem>
            <para>Specifies the password for the Subversion server to
              which you are syncing.  If not provided, or if
              incorrect, Subversion will prompt you for this
              information as needed.</para>
          </listitem>
        </varlistentry>
        
        <varlistentry>
          <term><option>--sync-username</option>
            <replaceable>NAME</replaceable></term>
          <listitem>
            <para>Specifies the username for the Subversion server to
              which you are syncing.  If not provided, or if
              incorrect, Subversion will prompt you for this
              information as needed.</para>
          </listitem>
        </varlistentry>

      </variablelist>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.ref.svnsync.c">
      <title>svnsync Subcommands</title>

      <para>Here are the various subcommands
        for the <command>svnsync</command> program.</para>

      <refentry id="svn.ref.svnsync.c.copy-revprops">

        <indexterm>
          <primary>svnsync</primary>
          <secondary>subcommands</secondary>
          <tertiary>copy-revprops</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnsync copy-revprops</refname>
          <refpurpose>Copy all revision properties for a particular
            revision (or range of revisions) from the source
            repository to the mirror repository.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnsync copy-revprops DEST_URL [REV[:REV2]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Because Subversion revision properties can be changed
            at any time, it's possible that the properties for some
            revision might be changed after that revision has already
            been synchronized to another repository.  Because the
            <command>svnsync synchronize</command> command operates
            only on the range of revisions that have not yet been
            synchronized, it won't notice a revision property change
            outside that range.  Left as is, this causes a deviation
            in the values of that revision's properties between the
            source and mirror repositories.  <command>svnsync
            copy-revprops</command> is the answer to this problem.
            Use it to resynchronize the revision properties for a
            particular revision or range of revisions.</para>
        </refsect1>

        <refsect1>
          <title>Alternate name</title>
          <para>None</para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--config-dir DIR
--no-auth-cache
--non-interactive
--quiet (-q)
--source-password ARG
--source-username ARG
--sync-password ARG
--sync-username ARG
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>Resynchronize revision properties for a single revision:</para>

          <screen>
$ svnsync copy-revprops file:///var/svn/repos-mirror 6
Copied properties for revision 6.
$
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnsync.c.help">

        <indexterm>
          <primary>svnsync</primary>
          <secondary>subcommands</secondary>
          <tertiary>help</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnsync help</refname> <refpurpose>Help!</refpurpose>
        </refnamediv>
        <refsect1>

          <title>Synopsis</title>
          <programlisting>svnsync help</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>This subcommand is useful when you're trapped in a
            foreign prison with neither a Net connection nor a copy of
            this book, but you do have a local Wi-Fi network running
            and you'd like to sync a copy of your repository over to
            the backup server that Ira The Knife is running over in
            cell block D.</para>
            
        </refsect1>

        <refsect1>
          <title>Alternate name</title>
          <para>None</para>
        </refsect1>

        <refsect1>
          <title>Options</title>
          <para>None</para>
        </refsect1>

      </refentry>

      <refentry id="svn.ref.svnsync.c.init">

        <indexterm>
          <primary>svnsync</primary>
          <secondary>subcommands</secondary>
          <tertiary>initialize</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnsync initialize</refname>
          <refpurpose>Initialize a mirror repository for
            synchronization from the source repository.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnsync initialize MIRROR_URL SOURCE_URL</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para><command>svnsync initialize</command> verifies that a
            repository meets the requirements of a new mirror
            repository&mdash;that it has no previous existing version
            history and that it allows revision property
            modifications&mdash;and records the initial administrative
            information that associates the mirror repository with
            the source repository.  This is the first
            <command>svnsync</command> operation you run on a would-be
            mirror repository.</para>
        </refsect1>

        <refsect1>
          <title>Alternate name</title>
          <para><command>init</command></para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--config-dir DIR
--no-auth-cache
--non-interactive
--quiet (-q)
--source-password ARG
--source-username ARG
--sync-password ARG
--sync-username ARG
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>Fail to initialize a mirror repository due to
            inability to modify revision properties:</para>

          <screen>
$ svnsync initialize file:///var/svn/repos-mirror http://svn.example.com/repos
svnsync: Repository has not been enabled to accept revision propchanges;
ask the administrator to create a pre-revprop-change hook
$
</screen>

          <para>Initialize a repository as a mirror, having already
            created a <literal>pre-revprop-change</literal> hook that
            permits all revision property changes:</para>

          <screen>
$ svnsync initialize file:///var/svn/repos-mirror http://svn.example.com/repos
Copied properties for revision 0.
$
</screen>

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svnsync.c.sync">

        <indexterm>
          <primary>svnsync</primary>
          <secondary>subcommands</secondary>
          <tertiary>synchronize</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svnsync synchronize</refname>
          <refpurpose>Transfer all pending revisions from the source
            repository to the mirror repository.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svnsync synchronize DEST_URL</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>The <command>svnsync synchronize</command> command
            does all the heavy lifting of a repository mirroring
            operation.  After consulting with the mirror repository to
            see which revisions have already been copied into it, it
            then begins to copy any not-yet-mirrored revisions from
            the source repository.</para>

          <para><command>svnsync synchronize</command> can be
            gracefully canceled and restarted.</para>

          <para>As of Subversion 1.5, you can limit <command>svnsync</command> to a
            subdirectory of the source repository by specifying the
            subdirectory as part of
            the <replaceable>SOURCE_URL</replaceable>.</para>

        </refsect1>

        <refsect1>
          <title>Alternate name</title>
          <para><command>sync</command></para>
        </refsect1>

        <refsect1>
          <title>Options</title>

          <screen>
--config-dir DIR
--no-auth-cache
--non-interactive
--quiet (-q)
--source-password ARG
--source-username ARG
--sync-password ARG
--sync-username ARG
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

          <para>Copy unsynchronized revisions from the source
            repository to the mirror repository:</para>

          <screen>
$ svnsync synchronize file:///var/svn/repos-mirror
Committed revision 1.
Copied properties for revision 1.
Committed revision 2.
Copied properties for revision 2.
Committed revision 3.
Copied properties for revision 3.
&hellip;
Committed revision 45.
Copied properties for revision 45.
Committed revision 46.
Copied properties for revision 46.
Committed revision 47.
Copied properties for revision 47.
$
</screen>

        </refsect1>

      </refentry>
    </sect2>

  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.ref.svnserve">

    <title>svnserve</title>
    
    <para><command>svnserve</command> allows access to Subversion
      repositories using Subversion's custom network protocol.</para>

    <para>You can run <command>svnserve</command> as a standalone
      server process (for clients that are using the
      <literal>svn://</literal> access method); you can have a daemon
      such as <command>inetd</command> or <command>xinetd</command>
      launch it for you on demand (also for
      <literal>svn://</literal>), or you can have
      <command>sshd</command> launch it on demand for the
      <literal>svn+ssh://</literal> access method.</para>

    <para>Regardless of the access method, once the client has
      selected a repository by transmitting its URL,
      <command>svnserve</command> reads a file named
      <filename>conf/svnserve.conf</filename> in the repository
      directory to determine repository-specific settings such as
      what authentication database to use and what authorization
      policies to apply.  See <xref
      linkend="svn.serverconfig.svnserve"/> for details of the
      <filename>svnserve.conf</filename> file.</para>
    
    <!-- =============================================================== -->
    <sect2 id="svn.ref.svnserve.sw">
      <title>svnserve Options</title>
      
      <para>Unlike the previous commands we've
        described, <command>svnserve</command> has no
        subcommands&mdash;it is controlled exclusively by
        options.</para>

      <variablelist>

        <varlistentry>
          <term><option>--daemon</option> (<option>-d</option>)</term>
          <listitem>
            <para>Causes <command>svnserve</command> to run in daemon
              mode.  <command>svnserve</command> backgrounds itself
              and accepts and serves TCP/IP connections on
              the <literal>svn</literal> port (3690, by
              default).</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--foreground</option></term>
          <listitem>
            <para>When used together with <option>-d</option>,
              causes <command>svnserve</command> to stay in the
              foreground.  This is mainly useful for debugging.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--inetd</option> (<option>-i</option>)</term>
          <listitem>
            <para>Causes <command>svnserve</command> to use the
              <filename>stdin</filename> and <filename>stdout</filename> file descriptors, as is appropriate for a
              daemon running out of <command>inetd</command>.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--help</option> (<option>-h</option>)</term>
          <listitem>
            <para>Displays a usage summary and exits.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--listen-host</option>=<replaceable>HOST</replaceable></term>
          <listitem>
            <para>Causes <command>svnserve</command> to listen on the
              interface specified by <replaceable>HOST</replaceable>,
              which may be either a hostname or an IP address.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--listen-once</option> (<option>-X</option>)</term>
          <listitem>
            <para>Causes <command>svnserve</command> to accept one
              connection on the <literal>svn</literal> port, serve it,
              and exit.  This option is mainly useful for
              debugging.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--listen-port</option>=<replaceable>PORT</replaceable></term>
          <listitem>
            <para>Causes <command>svnserve</command> to listen on
              <replaceable>PORT</replaceable> when run in daemon mode.
              (FreeBSD daemons listen only on tcp6 by default&mdash;this
              option tells them to also listen on tcp4.)</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--pid-file <replaceable>FILENAME</replaceable></option></term>
          <listitem>
            <para>Causes <command>svnserve</command> to write its
              process ID to <replaceable>FILENAME</replaceable>, which
              must be writable by the user under
              which <command>svnserve</command> is running.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--root</option>=<replaceable>ROOT</replaceable>
          (<option>-r</option>=<replaceable>ROOT</replaceable>)</term>
          <listitem>
            <para>Sets the virtual root for repositories served by
              <command>svnserve</command>.  The pathname in URLs
              provided by the client will be interpreted relative to
              this root and will not be allowed to escape this
              root.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--threads</option> (<option>-T</option>)</term>
          <listitem>
            <para>When running in daemon mode, causes
              <command>svnserve</command> to spawn a thread instead of
              a process for each connection (e.g., for when running on
              Windows).  The <command>svnserve</command> process still
              backgrounds itself at startup time.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--tunnel</option> (<option>-t</option>)</term>
          <listitem>
            <para>Causes <command>svnserve</command> to run in tunnel
              mode, which is just like the <command>inetd</command>
              mode of operation (both modes serve one connection over
              <filename>stdin</filename>/<filename>stdout</filename>, and then exit), except that the connection
              is considered to be preauthenticated with the username
              of the current UID.  This flag is automatically passed
              for you by the client when running over a tunnel agent
              such as <command>ssh</command>.  That means there's
              rarely any need for <emphasis>you</emphasis> to pass
              this option to <command>svnserve</command>.  So, if you
              find yourself
              typing <literal>svnserve --tunnel</literal> on the
              command line and wondering what to do next, see
              <xref linkend="svn.serverconfig.svnserve.sshauth"/>.
              </para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--tunnel-user NAME</option></term>
          <listitem>
            <para>Used in conjunction with the <option>--tunnel</option>
              option, tells <command>svnserve</command> to assume that
              <replaceable>NAME</replaceable> is the authenticated
              user, rather than the UID of the <command>svnserve</command>
              process.  This is useful for users wishing to share a single
              system account over SSH, but to maintain separate commit
              identities.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--version</option></term>
          <listitem>
            <para>Displays version information and a list of repository
            backend modules available, and then exits.</para>
          </listitem>
        </varlistentry>

      </variablelist>

    </sect2>

  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.ref.svndumpfilter">
    <title>svndumpfilter</title>
    
    <para><command>svndumpfilter</command> is a command-line utility
      for removing history from a Subversion dump file by either
      excluding or including paths beginning with one or more named
      prefixes.  For details, see
      <xref linkend="svn.reposadmin.maint.tk.svndumpfilter"/>.</para>

    <!-- =============================================================== -->
    <sect2 id="svn.ref.svndumpfilter.options">
      <title>svndumpfilter Options</title>
      
      <para>Options in <command>svndumpfilter</command> are global, just
        as they are in <command>svn</command> and
        <command>svnadmin</command>:</para>

      <variablelist>

        <varlistentry>
          <term><option>--drop-empty-revs</option></term>
          <listitem>
            <para>If filtering causes any revision to be empty (i.e.,
              causes no change to the repository), removes these
              revisions from the final dump file.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--renumber-revs</option></term>
          <listitem>
            <para>Renumbers revisions that remain after
              filtering.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--skip-missing-merge-sources</option></term>
          <listitem>
            <para>Skips merge sources that have been removed as part of
              the filtering.  Without this
              option, <command>svndumpfilter</command> will exit with
              an error if the merge source for a retained path is
              removed by filtering.</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--preserve-revprops</option></term>
          <listitem>
            <para>If all nodes in a revision are removed by filtering
              and <option>--drop-empty-revs</option> is not passed,
              the default behavior of <command>svndumpfilter</command>
              is to remove all revision properties except for the date
              and the log message (which will merely indicate that the
              revision is empty).  Passing this option will preserve
              existing revision properties (which may or may not make
              sense since the related content is no longer present in
              the dump file).</para>
          </listitem>
        </varlistentry>

        <varlistentry>
          <term><option>--quiet</option></term>
          <listitem>
            <para>Does not display filtering statistics.</para>
          </listitem>
        </varlistentry>

      </variablelist>

    </sect2>

    <!-- =============================================================== -->
    <sect2 id="svn.ref.svndumpfilter.c">
      <title>svndumpfilter Subcommands</title>

      <para>Here are the various subcommands
        for the <command>svndumpfilter</command> program.</para>

      <refentry id="svn.ref.svndumpfilter.commands.c.exclude">

        <indexterm>
          <primary>svndumpfilter</primary>
          <secondary>subcommands</secondary>
          <tertiary>exclude</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svndumpfilter exclude</refname>
          <refpurpose>Filter out nodes with given prefixes from the dump stream.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svndumpfilter exclude PATH_PREFIX...</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>This can be used to exclude nodes that begin with one or
            more <replaceable>PATH_PREFIX</replaceable>es from a
            filtered dump file.</para>
        </refsect1>

        <refsect1>
          <title>Options</title>
          
          <screen>
--drop-empty-revs
--preserve-revprops
--quiet
--renumber-revs
--skip-missing-merge-sources
</screen>
        </refsect1>

        <refsect1>
          <title>Examples</title>

        <para>If we have a dump file from a repository with a number of
          different picnic-related directories in it, but we want to keep
          everything <emphasis>except</emphasis>
          the <filename>sandwiches</filename> part of the repository,
          we'll exclude only that path:</para>

          <screen>
$ svndumpfilter exclude sandwiches &lt; dumpfile &gt; filtered-dumpfile
Excluding prefixes:
   '/sandwiches'

Revision 0 committed as 0.
Revision 1 committed as 1.
Revision 2 committed as 2.
Revision 3 committed as 3.
Revision 4 committed as 4.

Dropped 1 node(s):
   '/sandwiches'
</screen>            

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svndumpfilter.commands.c.include">

        <indexterm>
          <primary>svndumpfilter</primary>
          <secondary>subcommands</secondary>
          <tertiary>include</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svndumpfilter include</refname>
          <refpurpose>Filter out nodes without given prefixes from
            dump stream.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svndumpfilter include PATH_PREFIX...</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Can be used to include nodes that begin with one or
            more <replaceable>PATH_PREFIX</replaceable>es in a
            filtered dump file (thus excluding all other paths).</para>
        </refsect1>

        <refsect1>
          <title>Options</title>
          
          <screen>
--drop-empty-revs
--preserve-revprops
--quiet
--renumber-revs
--skip-missing-merge-sources
</screen>
        </refsect1>

        <refsect1>
          <title>Example</title>

        <para>If we have a dump file from a repository with a number of
          different picnic-related directories in it, but want to
          keep only the <filename>sandwiches</filename> part of the
          repository, we'll include only that path:</para>

          <screen>
$ svndumpfilter include sandwiches &lt; dumpfile &gt; filtered-dumpfile
Including prefixes:
   '/sandwiches'

Revision 0 committed as 0.
Revision 1 committed as 1.
Revision 2 committed as 2.
Revision 3 committed as 3.
Revision 4 committed as 4.

Dropped 3 node(s):
   '/drinks'
   '/snacks'
   '/supplies'
</screen>            

        </refsect1>
      </refentry>

      <refentry id="svn.ref.svndumpfilter.commands.c.help">

        <indexterm>
          <primary>svndumpfilter</primary>
          <secondary>subcommands</secondary>
          <tertiary>help</tertiary>
        </indexterm>

        <refnamediv>
          <refname>svndumpfilter help</refname>
          <refpurpose>Help!.</refpurpose>
        </refnamediv>
        <refsect1>
          <title>Synopsis</title>
          <programlisting>svndumpfilter help [SUBCOMMAND...]</programlisting>
        </refsect1>
        <refsect1>
          <title>Description</title>

          <para>Displays the help message
            for <command>svndumpfilter</command>.  Unlike other help
            commands documented in this chapter, there is no witty
            commentary for this help command.  The authors of this
            book deeply regret the omission.</para>
        </refsect1>

        <refsect1>
          <title>Options</title>
          <para>None</para>
        </refsect1>

      </refentry>

    </sect2>
  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.ref.svnversion">

    <title>svnversion</title>
    
    <refentry id="svn.ref.svnversion.re">

      <indexterm>
        <primary>svnversion</primary>
      </indexterm>

      <refnamediv>
        <refname>svnversion</refname>
        <refpurpose>Summarize the local revision(s) of a working
                    copy.</refpurpose>
      </refnamediv>

      <refsect1 id="svn.ref.svnversion.re.syn">
        <title>Synopsis</title>
        <programlisting>svnversion [OPTIONS] [WC_PATH [TRAIL_URL]]</programlisting>
      </refsect1>

      <refsect1 id="svn.ref.svnversion.re.desc">
        <title>Description</title>

        <para><command>svnversion</command> is a program for
          summarizing the revision mixture of a working copy.  The
          resultant revision number, or revision range, is written to
          standard output.</para>

        <para>It's common to use this output in your build process
          when defining the version number of your program.</para>
        
        <para><replaceable>TRAIL_URL</replaceable>, if present, is the
          trailing portion of the URL used to determine whether
          <replaceable>WC_PATH</replaceable> itself is switched
          (detection of switches within
          <replaceable>WC_PATH</replaceable> does not rely on
          <replaceable>TRAIL_URL</replaceable>).</para>

        <para>When <replaceable>WC_PATH</replaceable> is not defined,
          the current directory will be used as the working copy path.
          <replaceable>TRAIL_URL</replaceable> cannot be defined if
          <replaceable>WC_PATH</replaceable> is not explicitly
          given.</para>
  
      </refsect1>

      <refsect1 id="svn.ref.svnversion.re.sw">
        <title>Options</title>

        <para>Like <command>svnserve</command>,
          <command>svnversion</command> has no subcommands&mdash;only
          options:</para>

        <variablelist>
    
          <varlistentry>
            <term><option>--no-newline</option> (<option>-n</option>)</term>
            <listitem>
              <para>Omits the usual trailing newline from the output.</para>
            </listitem>
          </varlistentry>
    
          <varlistentry>
            <term><option>--committed</option> (<option>-c</option>)</term>
            <listitem>
              <para>Uses the last-changed revisions rather than the
              current (i.e., highest locally available) revisions.</para>
            </listitem>
          </varlistentry>
    
          <varlistentry>
            <term><option>--help</option> (<option>-h</option>)</term>
            <listitem>
              <para>Prints a help summary.</para>
            </listitem>
          </varlistentry>
    
          <varlistentry>
            <term><option>--version</option></term>
            <listitem>
              <para>Prints the version of <command>svnversion</command>
              and exit with no error.</para>
            </listitem>
          </varlistentry>

        </variablelist>
      </refsect1>

      <refsect1 id="svn.ref.svnversion.re.examples">
        <title>Examples</title>

        <para>If the working copy is all at the same revision (e.g.,
          immediately after an update), then that revision is
          printed out:</para>

        <screen>
$ svnversion
4168
</screen>

        <para>You can add <replaceable>TRAIL_URL</replaceable> to make
          sure the working copy is not switched from what you
          expect.  Note that the <replaceable>WC_PATH</replaceable>
          is required in this command:</para>

        <screen>
$ svnversion . /var/svn/trunk
4168
</screen>

        <para>For a mixed-revision working copy, the range of
          revisions present is printed:</para>

        <screen>
$ svnversion
4123:4168
</screen>

        <para>If the working copy contains modifications, a trailing
          "M" is added:</para>

        <screen>
$ svnversion
4168M
</screen>

        <para>If the working copy is switched, a trailing "S" is
          added:</para> 

        <screen>
$ svnversion
4168S
</screen>

        <para>Thus, here is a mixed-revision, switched working copy
          containing some local modifications:</para>

        <screen>
$ svnversion
4212:4168MS
</screen>

        <para>If invoked on a directory that is not a working copy,
          <command>svnversion</command> assumes it is an exported
          working copy and prints "exported":</para>

        <screen>
$ svnversion
exported
</screen>

      </refsect1>

    </refentry>
  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.ref.mod_dav_svn">

    <title>mod_dav_svn</title>
    
    <refentry id="svn.ref.mod_dav_svn.conf">
      <refnamediv>

        <refname>mod_dav_svn Configuration Directives</refname>
        <refpurpose>Apache configuration
        directives for serving Subversion repositories through the
        Apache HTTP Server.</refpurpose>

      </refnamediv>

      <refsect1 id="svn.ref.mod_dav_svn.conf.desc">
        <title>Description</title>

        <para>This section briefly describes each Subversion
          Apache configuration directive.  For an in-depth
          description of configuring Apache with Subversion, see <xref
          linkend="svn.serverconfig.httpd"/>.)</para>

      </refsect1>

      <refsect1 id="svn.ref.mod_dav_svn.conf.directives">
        <title>Directives</title>

        <para>These are the <filename>httpd.conf</filename> directives
          that apply to <command>mod_dav_svn</command>:</para>

        <variablelist>
    
          <varlistentry>
            <term><literal>DAV svn</literal></term>
            <listitem>

              <para>Must be included in any
                <literal>Directory</literal> or
                <literal>Location</literal> block for a Subversion
                repository.  It tells <command>httpd</command> to use the Subversion
                backend for <literal>mod_dav</literal> to handle all
                requests.</para>

            </listitem>
          </varlistentry>

          <varlistentry>
            <term><literal>SVNAllowBulkUpdates On|Off</literal></term>
            <listitem>

              <para>Toggles support for all-inclusive
                responses to update-style <literal>REPORT</literal>
                requests.  Subversion clients use
                <literal>REPORT</literal> requests to get information
                about directory tree checkouts and updates from
                <command>mod_dav_svn</command>.  They can ask the
                server to send that information in one of two ways:
                with the entirety of the tree's information in one
                massive response, or with a
                <firstterm>skelta</firstterm> (a skeletal
                representation of a tree delta) which contains just
                enough information for the client to know what
                <emphasis>additional</emphasis> data to request from
                the server.  When this directive is included with a
                value of <literal>Off</literal>,
                <command>mod_dav_svn</command> will only ever respond
                to these <literal>REPORT</literal> requests with
                skelta responses, regardless of the type of responses
                requested by the client.</para>

              <para>Most folks won't need to use this directive at
                all.  It primarily exists for administrators who
                wish&mdash;for security or auditing reasons&mdash;to
                force Subversion clients to fetch individually all the
                files and directories needed for updates and
                checkouts, thus leaving an audit trail of
                <literal>GET</literal> and <literal>PROPFIND</literal>
                requests in Apache's logs.  The default value of this
                directive is <literal>On</literal>.</para>

            </listitem>
          </varlistentry>
          <varlistentry>
            <term><literal>SVNAutoversioning On|Off</literal></term>
            <listitem>

              <para>When its value is
                <literal>On</literal>, allows write requests from
                WebDAV clients to result in automatic commits.  A
                generic log message is auto-generated and attached to
                each revision.  If you enable autoversioning, you'll
                likely want to set <literal>ModMimeUsePathInfo
                On</literal> so that <literal>mod_mime</literal> can
                set <literal>svn:mime-type</literal> to the correct
                MIME type automatically (as best as
                <literal>mod_mime</literal> is able to, of course).
                For more information, see <xref
                linkend="svn.webdav"/>.  The default value of this
                directive is <literal>Off</literal>.</para>

            </listitem>
          </varlistentry>

          <varlistentry>
            <term><literal>SVNPath
              <replaceable>directory-path</replaceable></literal></term>
            <listitem>

              <para>Specifies the location in the
                filesystem for a Subversion repository's files.  In a
                configuration block for a Subversion repository,
                either this directive or
                <literal>SVNParentPath</literal> must be present, but
                not both.</para>

            </listitem>
          </varlistentry>

          <varlistentry>
            <term><literal>SVNSpecialURI
              <replaceable>component</replaceable></literal></term>
            <listitem>

              <para>Specifies the URI component (namespace) for
                special Subversion resources.  The default is
                <literal>!svn</literal>, and most
                administrators will never use this directive.  Set
                this only if there is a pressing need to have a file
                named <filename>!svn</filename> in your repository.
                If you change this on a server already in use, it will
                break all of the outstanding working copies, and your
                users will hunt you down with pitchforks and flaming
                torches.</para>

            </listitem>
          </varlistentry>

          <varlistentry>
            <term><literal>SVNReposName
              <replaceable>name</replaceable></literal></term>
            <listitem>

              <para>Specifies the name of a Subversion repository for
                use in <literal>HTTP GET</literal> responses.  This
                value will be prepended to the title of all directory
                listings (which are served when you navigate to a
                Subversion repository with a web browser).  This
                directive is optional.</para>

            </listitem>
          </varlistentry>

          <varlistentry>
            <term><literal>SVNIndexXSLT
              <replaceable>directory-path</replaceable></literal></term>
            <listitem>

              <para>Specifies the URI of an XSL transformation for
                directory indexes.  This directive is optional.</para>

            </listitem>
          </varlistentry>

          <varlistentry>
            <term><literal>SVNParentPath
              <replaceable>directory-path</replaceable></literal></term>
            <listitem>

              <para>Specifies the location in the filesystem of a
                parent directory whose child directories are
                Subversion repositories.  In a configuration block for
                a Subversion repository, either this directive or
                <literal>SVNPath</literal> must be present, but not
                both.</para>

            </listitem>
          </varlistentry>

          <varlistentry>
            <term><literal>SVNPathAuthz On|Off|short_circuit</literal></term>
            <listitem>

              <para>Controls path-based authorization by enabling
                subrequests (<literal>On</literal>), disabling
                subrequests (<literal>Off</literal>; see <xref
                linkend="svn.serverconfig.httpd.authz.pathauthzoff"/>),
                or querying <command>mod_authz_svn</command> directly
                (<literal>short_circuit</literal>).  The default
                value of this directive is <literal>On</literal>.</para>

            </listitem>
          </varlistentry>

          <varlistentry>
            <term><literal>SVNListParentPath On|Off</literal></term>
            <listitem>

              <para>When set to <literal>On</literal>, allows
                a <literal>GET</literal>
                of <literal>SVNParentPath</literal>, which results in
                a listing of all repositories under that path.  The
                default setting is
                <literal>Off</literal>.</para>

            </listitem>
          </varlistentry>

          <varlistentry>
            <term><literal>SVNMasterURI
              <replaceable>url</replaceable></literal></term>
            <listitem>

              <para>Specifies a URI to the master Subversion
                repository (used for a write-through proxy).</para>

            </listitem>
          </varlistentry>

          <varlistentry>
            <term><literal>SVNActivitiesDB
              <replaceable>directory-path</replaceable></literal></term>
            <listitem>

              <para>Specifies the location in the filesystem where the
                activities database should be stored.  By default,
                <command>mod_dav_svn</command> creates and uses a directory in the
                repository
                called <filename>dav/activities.d</filename>.  The
                path specified with this option must be an absolute
                path.</para>

              <para>If specified for
                an <literal>SVNParentPath</literal> area, <command>mod_dav_svn</command>
                appends the basename of the repository to the path
                specified here.  For example:</para>

        <screen>
&lt;Location /svn&gt;
  DAV svn

  # any "/svn/foo" URL will map to a repository in 
  # /net/svn.nfs/repositories/foo
  SVNParentPath         "/net/svn.nfs/repositories"

  # any "/svn/foo" URL will map to an activities db in
  #  /var/db/svn/activities/foo
  SVNActivitiesDB       "/var/db/svn/activities"
&lt;/Location&gt;
</screen>

            </listitem>
          </varlistentry>

        </variablelist>
      </refsect1>

      <refsect1 id="svn.ref.mod_dav_svn.conf.logging">
        <title>High-level logging</title>
        
        <para>This is a list of Subversion action log messages
          produced by Apache's high-level logging mechanism, followed
          by an example of the log message.  See <xref
          linkend="svn.serverconfig.httpd.extra.logging"/> for details
          on logging.</para>

        <variablelist>

          <varlistentry>
            <term>Checkout or export</term>
            <listitem>
              <para><literal>checkout-or-export /path r62
            depth=infinity</literal></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Commit</term>
            <listitem>
              <para><literal>commit harry r100</literal></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Diffs</term>
            <listitem>
              <para><literal>diff /path r15:20 depth=infinity ignore-ancestry</literal></para>
              <para><literal>diff /path1@15 /path2@20 depth=infinity ignore-ancestry</literal></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Fetch a directory</term>
            <listitem>
              <para><literal>get-dir /trunk r17 text</literal></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Fetch a file</term>
            <listitem>
              <para><literal>get-file /path r20 props</literal></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Fetch a file revision</term>
            <listitem>
              <para><literal>get-file-revs /path r12:15 include-merged-revisions</literal></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Fetch merge information</term>
            <listitem>
              <para><literal>get-mergeinfo (/path1 /path2)</literal></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Lock</term>
            <listitem>
              <para><literal>lock /path steal</literal></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Log</term>
            <listitem>
              <para><literal>log (/path1,/path2,/path3) r20:90
            discover-changed-paths revprops=()</literal></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Replay revisions (svnsync)</term>
            <listitem>
              <para><literal>replay /path r19</literal></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Revision property change</term>
            <listitem>
              <para><literal>change-rev-prop r50
            propertyname</literal></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Revision property list</term>
            <listitem>
              <para><literal>rev-proplist r34</literal></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Status</term>
            <listitem>
              <para><literal>status /path r62
                depth=infinity</literal></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Switch</term>
            <listitem>
              <para><literal>switch /pathA /pathB@50 depth=infinity</literal></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Unlock</term>
            <listitem>
              <para><literal>unlock /path break</literal></para>
            </listitem>
          </varlistentry>

          <varlistentry>
            <term>Update</term>
            <listitem>
              <para><literal>update /path r17 send-copyfrom-args</literal></para>
            </listitem>
          </varlistentry>

        </variablelist>

      </refsect1>

    </refentry>
  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.ref.mod_authz_svn">

    <title>mod_authz_svn</title>
    
    <refentry id="svn.ref.mod_authz_svn.conf">
      <refnamediv>

        <refname>mod_authz_svn Configuration Directives</refname>
        <refpurpose>Apache configuration directives for configuring
        path-based authorization for Subversion repositories served
        through the Apache HTTP Server.</refpurpose>

      </refnamediv>

      <refsect1 id="svn.ref.mod_authz_svn.conf.desc">
        <title>Description</title>

        <para>This section briefly describes each Apache configuration
          directive offered by <command>mod_authz_svn</command>.  For
          an in-depth description of using path-based authorization in
          Subversion, see <xref linkend="svn.serverconfig.pathbasedauthz"/>.)</para>

      </refsect1>

      <refsect1 id="svn.ref.mod_authz_svn.conf.directives">
        <title>Directives</title>

        <para>These are the <filename>httpd.conf</filename> directives
          that apply to <command>mod_authz_svn</command>:</para>

        <variablelist>
   
          <varlistentry>
            <term><literal>AuthzSVNAccessFile
              <replaceable>file-path</replaceable></literal></term>
            <listitem>

              <para>Consult <replaceable>file-path</replaceable> for
                access rules describing the permissions for paths in
                Subversion repository.</para>

            </listitem>
          </varlistentry>

          <varlistentry>
            <term><literal>AuthzSVNAnonymous On|Off</literal></term>
            <listitem>

              <para>Set to <literal>Off</literal> to disable two
                special-case behaviours of this module: interaction
                with the <literal>Satisfy Any</literal> directive and
                enforcement of the authorization policy even when no
                <literal>Require</literal> directives are present.
                The default value of this directive is
                <literal>On</literal>.</para>

            </listitem>
          </varlistentry>

          <varlistentry>
            <term><literal>AuthzSVNAuthoritative On|Off</literal></term>
            <listitem>

              <para>Set to <literal>Off</literal> to allow access
                control to be passed along to lower modules.  The
                default value of this directive is
                <literal>On</literal>.</para>

            </listitem>
          </varlistentry>

          <varlistentry>
            <term><literal>AuthzSVNNoAuthWhenAnonymousAllowed On|Off</literal></term>
            <listitem>

              <para>Set to <literal>On</literal> to suppress
                authentication and authorization for requests which
                anonymous users are allowed to perform.  The default
                value of this directive is
                <literal>On</literal>.</para>

            </listitem>
          </varlistentry>

        </variablelist>
      </refsect1>

    </refentry>
  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.ref.properties">

    <title>Subversion Properties</title>

    <para>Subversion allows users to invent arbitrarily named
      versioned properties on files and directories, as well as
      unversioned properties on revisions.  The only restriction is on
      properties whose names begin with <literal>svn:</literal> (those
      are reserved for Subversion's own use).  While these properties
      may be set by users to control Subversion's behavior, users may
      not invent new <literal>svn:</literal> properties.</para>

    <sect2 id="svn.ref.properties.versioned-props">
      <title>Versioned Properties</title>

      <para>These are the versioned properties that Subversion reserves
        for its own use:</para>

      <variablelist>

        <varlistentry>
          <term><literal>svn:executable</literal></term>
          <listitem>

            <para>If present on a file, the client will make the
              file executable in Unix-hosted working copies.  See
              <xref
              linkend="svn.advanced.props.special.executable"/>.</para>

          </listitem>
        </varlistentry>

        <varlistentry>
          <term><literal>svn:mime-type</literal></term>
          <listitem>

            <para>If present on a file, the value indicates the
              file's MIME type.  This allows the client to decide
              whether line-based contextual merging is safe to
              perform during updates, and can also affect how the
              file behaves when fetched via a web browser.  See
              <xref
              linkend="svn.advanced.props.special.mime-type"/>. </para>

          </listitem>
        </varlistentry>

        <varlistentry>
          <term><literal>svn:ignore</literal></term>
          <listitem>

            <para>If present on a directory, the value is a list of
              <emphasis>unversioned</emphasis> file patterns to be ignored
              by <command>svn status</command> and other
              subcommands.  See
              <xref
              linkend="svn.advanced.props.special.ignore"/>.</para>

          </listitem>
        </varlistentry>

        <varlistentry>
          <term><literal>svn:keywords</literal></term>
          <listitem>

            <para>If present on a file, the value tells the client
              how to expand particular keywords within the file.
              See
              <xref
              linkend="svn.advanced.props.special.keywords"/>.</para>

          </listitem>
        </varlistentry>

        <varlistentry>
          <term><literal>svn:eol-style</literal></term>
          <listitem>

            <para>If present on a file, the value tells the client how
              to manipulate the file's line-endings in the working
              copy and in exported trees.  See <xref
              linkend="svn.advanced.props.special.eol-style"/> and
              <xref linkend="svn.ref.svn.c.export" /> earlier in this chapter.</para>

          </listitem>
        </varlistentry>

        <varlistentry>
          <term><literal>svn:externals</literal></term>
          <listitem>

            <para>If present on a directory, the value is a multiline
              list of other paths and URLs the client should check
              out.  See
              <xref linkend="svn.advanced.externals"/>.</para>

          </listitem>
        </varlistentry>

        <varlistentry>
          <term><literal>svn:special</literal></term>
          <listitem>

            <para>If present on a file, indicates that the file is not
              an ordinary file, but a symbolic link or other special
              object.
              <footnote>
                <para>As of this writing, symbolic links are indeed
                  the only <quote>special</quote> objects.  But there
                  might be more in future releases of
                  Subversion.</para>
              </footnote>
            </para>

          </listitem>
        </varlistentry>

        <varlistentry>
          <term><literal>svn:needs-lock</literal></term>
          <listitem>

            <para>If present on a file, tells the client to make the
              file read-only in the working copy, as a reminder that
              the file should be locked before editing begins.  See
              <xref
              linkend="svn.advanced.locking.lock-communication"/>.</para>

          </listitem>
        </varlistentry>

        <varlistentry>
          <term><literal>svn:mergeinfo</literal></term>
          <listitem>

            <para>Used by Subversion to track merge data.  See
              <xref linkend="svn.branchmerge.basicmerging.mergeinfo"/>
              for details, but you should never edit this property
              unless you <emphasis>really</emphasis> know what you're
              doing.</para>

          </listitem>
        </varlistentry>

      </variablelist>
    </sect2>

    <sect2 id="svn.ref.properties.unversioned-props">
      <title>Unversioned Properties</title>

      <para>These are the unversioned properties tht Subversion reserves
        for its own use:</para>

      <variablelist>

        <varlistentry>
          <term><literal>svn:author</literal></term>
          <listitem>

            <para>If present, contains the authenticated username of
              the person who created the revision.  (If not present,
              the revision was committed anonymously.)</para>

          </listitem>
        </varlistentry>

        <varlistentry>
          <term><literal>svn:date</literal></term>
          <listitem>

            <para>Contains the UTC time the revision was created, in
              ISO 8601 format.  The value comes from the
              <emphasis>server</emphasis> machine's clock, not the
              client's.</para>

          </listitem>
        </varlistentry>

        <varlistentry>
          <term><literal>svn:log</literal></term>
          <listitem>

            <para>Contains the log message describing the
              revision.</para>

          </listitem>
        </varlistentry>

        <varlistentry>
          <term><literal>svn:autoversioned</literal></term>
          <listitem>

            <para>If present, the revision was created via the
              autoversioning feature.  See
              <xref linkend="svn.webdav.autoversioning"/>.</para>

          </listitem>
        </varlistentry>

      </variablelist>
    </sect2>

  </sect1>

  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <!-- ================================================================= -->
  <sect1 id="svn.ref.reposhooks">
  
    <title>Repository Hooks</title>

    <para>These are the repository hooks that Subversion provides:</para>
  
    <!-- =============================================================== -->
    <refentry id="svn.ref.reposhooks.start-commit">
  
      <indexterm>
        <primary>repository</primary>
        <secondary>hooks</secondary>
        <tertiary>start-commit</tertiary>
      </indexterm>

      <refnamediv>
        <refname>start-commit</refname>
        <refpurpose>Notification of the beginning of a commit.</refpurpose>
      </refnamediv>

      <refsect1>
        <title>Description</title>
        
        <para>The start-commit hook is run before the commit
          transaction is even created.  It is typically used to
          decide whether the user has commit privileges at all.</para>

        <para>If the start-commit hook program returns a nonzero exit
          value, the commit is stopped before the commit transaction
          is even created, and anything printed to <filename>stderr</filename> is
          marshalled back to the client.</para>

      </refsect1>

      <refsect1>
        <title>Input Parameter(s)</title>

        <para>The command-line arguments passed to the hook program,
          in order, are:</para>
        
        <orderedlist>
          <listitem>
            <para>Repository path</para>
          </listitem>
          <listitem>
            <para>Authenticated username attempting the commit</para>
          </listitem>
          <listitem>
            <para>Colon-separated list of
              capabilities that a client passes to the server,
              including <literal>depth</literal>,
              <literal>mergeinfo</literal>, and
              <literal>log-revprops</literal> (new in Subversion 1.5).</para>
          </listitem>
        </orderedlist>
      </refsect1>
      
      <refsect1>
        <title>Common uses</title>

        <para>Access control (e.g., temporarily lock out commits for
          some reason).</para>

        <para>A means to allow access only from clients that have
          certain capabilities.</para>
      </refsect1>

    </refentry>
        
    <!-- =============================================================== -->
    <refentry id="svn.ref.reposhooks.pre-commit">
  
      <indexterm>
        <primary>repository</primary>
        <secondary>hooks</secondary>
        <tertiary>pre-commit</tertiary>
      </indexterm>

      <refnamediv>
        <refname>pre-commit</refname>
        <refpurpose>Notification just prior to commit completion.</refpurpose>
      </refnamediv>

      <refsect1>
        <title>Description</title>

        <para>The <literal>pre-commit</literal> hook is run just
          before a commit transaction is promoted to a new revision.
          Typically, this hook is used to protect against commits that
          are disallowed due to content or location (e.g., your
          site might require that all commits to a certain branch
          include a ticket number from the bug tracker, or that the
          incoming log message is nonempty).</para>

        <para>If the <literal>pre-commit</literal> hook program
          returns a nonzero exit value, the commit is aborted, the
          commit transaction is removed, and anything printed to
          <filename>stderr</filename> is marshalled back to the client.</para>

      </refsect1>

      <refsect1>
        <title>Input parameter(s)</title>

        <para>The command-line arguments passed to the hook program,
          in order, are:</para>

        <orderedlist>
          <listitem>
            <para>Repository path</para>
          </listitem>
          <listitem>
            <para>Commit transaction name</para>
          </listitem>
        </orderedlist>
      </refsect1>
      
      <refsect1>
        <title>Common uses</title>
        <para>Change validation and control</para>
      </refsect1>
  
    </refentry>
        
    <!-- =============================================================== -->
    <refentry id="svn.ref.reposhooks.post-commit">
  
      <indexterm>
        <primary>repository</primary>
        <secondary>hooks</secondary>
        <tertiary>post-commit</tertiary>
      </indexterm>

      <refnamediv>
        <refname>post-commit</refname>
        <refpurpose>Notification of a successful commit.</refpurpose>
      </refnamediv>

      <refsect1>
        <title>Description</title>

        <para>The <literal>post-commit</literal> hook is run after the
          transaction is committed and a new revision is created.  Most
          people use this hook to send out descriptive emails about
          the commit or to notify some other tool (such as an issue
          tracker) that a commit has happened.  Some configurations
          also use this hook to trigger backup processes.</para>

        <para>If the <literal>post-commit</literal> hook returns a
          nonzero exit status, the commit <emphasis>will
          not</emphasis> be aborted since it has already
          completed.  However, anything that the hook printed
          to <filename>stderr</filename> will be marshalled back to the
          client, making it easier to diagnose hook failures.</para>
              
      </refsect1>

      <refsect1>
        <title>Input parameter(s)</title>

        <para>The command-line arguments passed to the hook program,
          in order, are:</para>
        
        <orderedlist>
          <listitem>
            <para>Repository path</para>
          </listitem>
          <listitem>
            <para>Revision number created by the commit</para>
          </listitem>
        </orderedlist>
      </refsect1>
      
      <refsect1>
        <title>Common uses</title>
        <para>Commit notification; tool integration</para>
      </refsect1>
  
    </refentry>
        
    <!-- =============================================================== -->
    <refentry id="svn.ref.reposhooks.pre-revprop-change">
  
      <indexterm>
        <primary>repository</primary>
        <secondary>hooks</secondary>
        <tertiary>pre-revprop-change</tertiary>
      </indexterm>

      <refnamediv>
        <refname>pre-revprop-change</refname>
        <refpurpose>Notification of a revision property change
          attempt.</refpurpose>
      </refnamediv>

      <refsect1>
        <title>Description</title>

        <para>The <literal>pre-revprop-change</literal> hook is run
          immediately prior to the modification of a revision property
          when performed outside the scope of a normal commit.  Unlike
          the other hooks, the default state of this one is to deny
          the proposed action.  The hook must actually exist and
          return a zero exit value before a revision property
          modification can happen.</para>

        <para>If the <literal>pre-revprop-change</literal> hook
          doesn't exist, isn't executable, or returns a nonzero exit
          value, no change to the property will be made, and anything
          printed to <filename>stderr</filename> is marshalled back to the client.</para>

      </refsect1>

      <refsect1>
        <title>Input parameter(s)</title>

        <para>The command-line arguments passed to the hook program,
          in order, are:</para>

        <orderedlist>
          <listitem>
            <para>Repository path</para>
          </listitem>
          <listitem>
            <para>Revision whose property is about to be modified</para>
          </listitem>
          <listitem>
            <para>Authenticated username attempting the property change</para>
          </listitem>
          <listitem>
            <para>Name of the property changed</para>
          </listitem>
          <listitem>
            <para>Change description: <literal>A</literal> (added),
              <literal>D</literal> (deleted), or <literal>M</literal>
              (modified)</para>
          </listitem>
        </orderedlist>

        <para>Additionally, Subversion passes the intended new value
           of the property to the hook program via standard
           input.</para>

      </refsect1>
      
      <refsect1>
        <title>Common uses</title>
        <para>Access control; change validation and control</para>
      </refsect1>
  
    </refentry>
        
    <!-- =============================================================== -->
    <refentry id="svn.ref.reposhooks.post-revprop-change">
  
      <indexterm>
        <primary>repository</primary>
        <secondary>hooks</secondary>
        <tertiary>post-revprop-change</tertiary>
      </indexterm>

      <refnamediv>
        <refname>post-revprop-change</refname>
        <refpurpose>Notification of a successful revision property 
          change.</refpurpose>
      </refnamediv>

      <refsect1>
        <title>Description</title>

        <para>The <literal>post-revprop-change</literal> hook is run
          immediately after the modification of a revision property
          when performed outside the scope of a normal commit.  As you can
          derive from the description of its counterpart, the
          <literal>pre-revprop-change</literal> hook, this hook will
          not run at all unless
          the <literal>pre-revprop-change</literal> hook is
          implemented.  It is typically used to send email
          notification of the property change.</para>

        <para>If the <literal>post-revprop-change</literal> hook returns a
          nonzero exit status, the change <emphasis>will
          not</emphasis> be aborted since it has already
          completed.  However, anything that the hook printed
          to <filename>stderr</filename> will be marshalled back to the
          client, making it easier to diagnose hook failures.</para>

      </refsect1>

      <refsect1>
        <title>Input parameter(s)</title>

        <para>The command-line arguments passed to the hook program,
          in order, are:</para>
        
        <orderedlist>
          <listitem>
            <para>Repository path</para>
          </listitem>
          <listitem>
            <para>Revision whose property was modified</para>
          </listitem>
          <listitem>
            <para>Authenticated username of the person making the change</para>
          </listitem>
          <listitem>
            <para>Name of the property changed</para>
          </listitem>
          <listitem>
            <para>Change description: <literal>A</literal> (added),
              <literal>D</literal> (deleted), or <literal>M</literal>
              (modified)</para>
          </listitem>
        </orderedlist>

        <para>Additionally, Subversion passes to the hook program, via
          standard input, the previous value of the property.</para>

      </refsect1>
      
      <refsect1>
        <title>Common uses</title>
        <para>Property change notification</para>
      </refsect1>
  
    </refentry>
        
    <!-- =============================================================== -->
    <refentry id="svn.ref.reposhooks.pre-lock">
  
      <indexterm>
        <primary>repository</primary>
        <secondary>hooks</secondary>
        <tertiary>pre-lock</tertiary>
      </indexterm>

      <refnamediv>
        <refname>pre-lock</refname>
        <refpurpose>Notification of a path lock attempt.</refpurpose>
      </refnamediv>

      <refsect1>
        <title>Description</title>

        <para>The <literal>pre-lock</literal> hook runs whenever
          someone attempts to lock a path.  It can be used to prevent
          locks altogether or to create a more complex policy
          specifying exactly which users are allowed to lock
          particular paths.  If the hook notices a preexisting lock,
          it can also decide whether a user is allowed
          to <quote>steal</quote> the existing lock.</para>

        <para>If the <literal>pre-lock</literal> hook program returns
          a nonzero exit value, the lock action is aborted and
          anything printed to <filename>stderr</filename> is marshalled back to the
          client.</para>

      </refsect1>

      <refsect1>
        <title>Input parameter(s)</title>

        <para>The command-line arguments passed to the hook program,
          in order, are:</para>
        
        <orderedlist>
          <listitem>
            <para>Repository path</para>
          </listitem>
          <listitem>
            <para>Versioned path that is to be locked</para>
          </listitem>
          <listitem>
            <para>Authenticated username of the person attempting the 
              lock</para>
          </listitem>
        </orderedlist>
      </refsect1>
      
      <refsect1>
        <title>Common uses</title>
        <para>Access control</para>
      </refsect1>
  
    </refentry>
        
    <!-- =============================================================== -->
    <refentry id="svn.ref.reposhooks.post-lock">
  
      <indexterm>
        <primary>repository</primary>
        <secondary>hooks</secondary>
        <tertiary>post-lock</tertiary>
      </indexterm>

      <refnamediv>
        <refname>post-lock</refname>
        <refpurpose>Notification of a successful path lock.</refpurpose>
      </refnamediv>

      <refsect1>
        <title>Description</title>

        <para>The <literal>post-lock</literal> hook runs after one or
          more paths have been locked.  It is typically used to send
          email notification of the lock event.</para>

        <para>If the <literal>post-lock</literal> hook returns a
          nonzero exit status, the lock <emphasis>will
          not</emphasis> be aborted since it has already
          completed.  However, anything that the hook printed
          to <filename>stderr</filename> will be marshalled back to the
          client, making it easier to diagnose hook failures.</para>

      </refsect1>

      <refsect1>
        <title>Input parameter(s)</title>

        <para>The command-line arguments passed to the hook program,
          in order, are:</para>
        
        <orderedlist>
          <listitem>
            <para>Repository path</para>
          </listitem>
          <listitem>
            <para>Authenticated username of the person who locked the 
              paths</para>
          </listitem>
        </orderedlist>

        <para>Additionally, the list of paths locked is passed to the
          hook program via standard input, one path per line.</para>

      </refsect1>
      
      <refsect1>
        <title>Common uses</title>
        <para>Lock notification</para>
      </refsect1>
  
    </refentry>
        
    <!-- =============================================================== -->
    <refentry id="svn.ref.reposhooks.pre-unlock">
  
      <indexterm>
        <primary>repository</primary>
        <secondary>hooks</secondary>
        <tertiary>pre-unlock</tertiary>
      </indexterm>

      <refnamediv>
        <refname>pre-unlock</refname>
        <refpurpose>Notification of a path unlock attempt.</refpurpose>
      </refnamediv>

      <refsect1>
        <title>Description</title>

        <para>The <literal>pre-unlock</literal> hook runs whenever
          someone attempts to remove a lock on a file.  It can be used
          to create policies that specify which users are allowed to
          unlock particular paths.  It's particularly important for
          determining policies about lock breakage.  If user A locks a
          file, is user B allowed to break the lock?  What if the lock
          is more than a week old?  These sorts of things can be
          decided and enforced by the hook.</para>

        <para>If the <literal>pre-unlock</literal> hook program
          returns a nonzero exit value, the unlock action is aborted
          and anything printed to <filename>stderr</filename> is marshalled back to the
          client.</para>

      </refsect1>

      <refsect1>
        <title>Input parameter(s)</title>

        <para>The command-line arguments passed to the hook program,
          in order, are:</para>
        
        <orderedlist>
          <listitem>
            <para>Repository path</para>
          </listitem>
          <listitem>
            <para>Versioned path which is to be locked</para>
          </listitem>
          <listitem>
            <para>Authenticated username of the person attempting the 
              lock</para>
          </listitem>
        </orderedlist>
      </refsect1>
      
      <refsect1>
        <title>Common uses</title>
        <para>Access control</para>
      </refsect1>
  
    </refentry>
        
    <!-- =============================================================== -->
    <refentry id="svn.ref.reposhooks.post-unlock">
  
      <indexterm>
        <primary>repository</primary>
        <secondary>hooks</secondary>
        <tertiary>post-unlock</tertiary>
      </indexterm>

      <refnamediv>
        <refname>post-unlock</refname>
        <refpurpose>Notification of a successful path unlock.</refpurpose>
      </refnamediv>

      <refsect1>
        <title>Description</title>

        <para>The <literal>post-unlock</literal> hook runs after one
          or more paths have been unlocked.  It is typically used to
          send email notification of the unlock event.</para>

        <para>If the <literal>post-unlock</literal> hook returns a
          nonzero exit status, the unlock <emphasis>will
          not</emphasis> be aborted since it has already
          completed.  However, anything that the hook printed
          to <filename>stderr</filename> will be marshalled back to the
          client, making it easier to diagnose hook failures.</para>

      </refsect1>

      <refsect1>
        <title>Input parameter(s)</title>

        <para>The command-line arguments passed to the hook program,
          in order, are:</para>
        
        <orderedlist>
          <listitem>
            <para>Repository path</para>
          </listitem>
          <listitem>
            <para>Authenticated username of the person who unlocked the 
              paths</para>
          </listitem>
        </orderedlist>

        <para>Additionally, the list of paths unlocked is passed to the
          hook program via standard input, one path per line.</para>

      </refsect1>
      
      <refsect1>
        <title>Common uses</title>
        <para>Unlock notification</para>
      </refsect1>
  
    </refentry>
  </sect1>
  
</chapter>

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

Show details Hide details

Change log

r3306 by cmpilato on Sep 15, 2008 Diff

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

Go to:

Older revisions

r3292 by cmpilato on Sep 3, 2008 Diff

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

r3288 by cmpilato on Sep 3, 2008 Diff

More minor typo tweaks from Øyvind A.
Holm <sunny@sunbase.org>, plus a
reworking of a couple of paragraphs
for readability and to avoid an
awkward use of an mid-sentence screen
...

r3265 by cmpilato on Aug 11, 2008 Diff

* src/en/book/ch09-reference.xml
  By way of followup to r3264, use a
capitalization and sentence
  structure pattern consistent with
other bits of the mod_X_svn
...

All revisions of this file

File info

Size: 319600 bytes, 9872 lines

View raw file

File properties

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