[svnbook] r4167 committed - * en/book/ch09-reference.xml...
svnbook at googlecode.com
svnbook at googlecode.com
Mon Nov 7 13:23:58 CST 2011
Revision: 4167
Author: cmpilato at gmail.com
Date: Mon Nov 7 11:23:27 2011
Log: * en/book/ch09-reference.xml
Begin a read-thru of the reference chapter, attempting to clarify
and correct where I can.
http://code.google.com/p/svnbook/source/detail?r=4167
Modified:
/trunk/en/book/ch09-reference.xml
=======================================
--- /trunk/en/book/ch09-reference.xml Thu Nov 3 15:01:37 2011
+++ /trunk/en/book/ch09-reference.xml Mon Nov 7 11:23:27 2011
@@ -15,11 +15,15 @@
<title>svn—Subversion Command-Line Client</title>
<para><command>svn</command> is the official command-line client
- of Subversion. It offers no small number of subcommands and
- options. Subcommands and other non-option arguments must appear
- in a specified order on the command line used to
- invoke <command>svn</command>. Options, on the other hand, may
- appear anywhere on the command line (after the program name, of
+ of Subversion. Its functionality is offered via a collection of
+ task-specific subcommands, most of which accept a number of
+ options for fine-grained control of the program's
+ behavior.</para>
+
+ <para>When using the <command>svn</command> program, subcommands
+ and other non-option arguments must appear in a specified order
+ on the command line. Options, on the other hand, may appear
+ anywhere on the command line (after the program name, of
course), and in general, their order is irrelevant. For
example, all of the following are valid ways to use <command>svn
status</command>, and are interpreted in exactly the same
@@ -35,6 +39,11 @@
</screen>
</informalexample>
+ <para>The following sections describe each of the various
+ subcommands and options provided by the <command>svn</command>
+ command-line client program, including some examples of each
+ subcommand's typical uses.</para>
+
<!-- ===============================================================
-->
<sect2 id="svn.ref.svn.sw">
<title>svn Options</title>
@@ -42,10 +51,11 @@
<para>While Subversion has different options for its
subcommands, all options exist in a single
namespace—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>
+ roughly 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
@@ -53,11 +63,42 @@
Subversion 1.5, several of the options which apply to
all—or nearly all—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>
+ effect on some of them. (This change was made primarily to
+ improve the client's ability to called from custom wrapping
+ scripts.) These options appear grouped together in the
+ command-line client's usage messages as global options, as can
+ be seen in the following bit of output:</para>
+
+ <informalexample>
+ <screen>
+$ svn help upgrade
+upgrade: Upgrade the metadata storage format for a working copy.
+usage: upgrade [WCPATH...]
+
+ Local modifications are preserved.
+
+Valid options:
+ -q [--quiet] : print nothing, or only summary information
+
+Global options:
+ --username ARG : specify a username ARG
+ --password ARG : specify a password ARG
+ --no-auth-cache : do not cache authentication tokens
+ --non-interactive : do no interactive prompting
+ --trust-server-cert : accept SSL server certificates from unknown
+ certificate authorities without prompting
(but only
+ with '--non-interactive')
+ --config-dir ARG : read user configuration files from directory
ARG
+ --config-option ARG : set user configuration option in the format:
+ FILE:SECTION:OPTION=[VALUE]
+ For example:
+ servers:global:http-library=serf
+$
+</screen>
+ </informalexample>
+
+ <para><command>svn</command> subcommands recognize the following
+ global options:</para>
<variablelist>
@@ -72,11 +113,15 @@
</varlistentry>
<varlistentry id="svn.ref.svn.sw.config_option">
- <term><option>--config-option</option>
<replaceable>FILE</replaceable>:<replaceable>SECTION</replaceable>:<replaceable>OPTION</replaceable>=[<replaceable>VALUE</replaceable>]</term>
+ <term><option>--config-option</option>
<replaceable>CONFSPEC</replaceable></term>
<listitem>
<para>Sets, for the duration of the command, the value of
a runtime configuration
- option. <replaceable>FILE</replaceable>
+ option. <replaceable>CONFSPEC</replaceable> is a string
+ which specifies the configuration option namespace, name
+ and value that you'd like to assign, formatted as
+
<replaceable>FILE</replaceable>:<replaceable>SECTION</replaceable>:<replaceable>OPTION</replaceable>=[<replaceable>VALUE</replaceable>].
+ In this syntax, <replaceable>FILE</replaceable>
and <replaceable>SECTION</replaceable> are the runtime
configuration file (either <literal>config</literal>
or <literal>servers</literal>) and the section thereof,
@@ -171,37 +216,45 @@
<listitem>
<para>Disables the verification—performed by default
by <command>svn merge</command> as of Subversion
- 1.7—that the items at and under the target
- directory of a merge operation are at a uniform
- revision. While merging into a single-revision working
- copy target is the recommended best practice, this
- option may be used to permit merges into mixed-revision
- working copies as necessary.</para>
+ 1.7—that the target of a merge operation and all
+ of its children are at a uniform revision. While
+ merging into a single-revision working copy target is
+ the recommended best practice, this option may be used
+ to permit merges into mixed-revision working copies as
+ necessary.</para>
</listitem>
</varlistentry>
<varlistentry id="svn.ref.svn.sw.auto_props">
<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>
+ <para>Enables automatic property assignment (per runtime
+ configuration rules), overriding the
+ <literal>enable-auto-props</literal> runtime
+ configuration directive.</para>
</listitem>
</varlistentry>
<varlistentry id="svn.ref.svn.sw.change">
<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>. If you
- wish to offer a range of revisions, some subcommands allow
- you to provide a comma separated list of args, e.g.
- <quote>-c ARG1,ARG2,ARG3</quote>. Alternatively, you can
- provide two arguments separated by a dash, e.g.
- <quote>-c ARG1:ARG2</quote>. This second form is
- syntactically equivalent to <quote>--range ARG1:ARG2</quote>
- but with ARG1 considered inclusive.</para>
+ <para>Perform the requested operation using a specific
+ <quote>change</quote>. Generally speaking, this option
+ is syntactic sugar for <userinput>-r
+
<replaceable>ARG-1</replaceable>:<replaceable>ARG</replaceable></userinput>.
+ Some subcommands permit a comma-separated list of
+ revision number arguments (e.g., <userinput>-c
+
<replaceable>ARG1</replaceable>,<replaceable>ARG2</replaceable>,<replaceable>ARG3</replaceable></userinput>).
+ Alternatively, you can provide two arguments separated
+ by a dash (as
+ in <userinput>-c
<replaceable>ARG1</replaceable>-<replaceable>ARG2</replaceable></userinput>)
+ to identify the range of revisions
+ between <replaceable>ARG1</replaceable>
+ and <replaceable>ARG2</replaceable>, inclusive.
+ Finally, if the revision argument is negated, the
+ implied revision range is reversed: <userinput>-c
+ -45</userinput> is equivalent to <userinput>-r
+ 45:44</userinput>.</para>
</listitem>
</varlistentry>
@@ -8875,11 +8928,15 @@
</varlistentry>
<varlistentry id="svn.ref.svnsync.sw.config_option">
- <term><option>--config-option</option>
<replaceable>FILE</replaceable>:<replaceable>SECTION</replaceable>:<replaceable>OPTION</replaceable>=[<replaceable>VALUE</replaceable>]</term>
+ <term><option>--config-option</option>
<replaceable>CONFSPEC</replaceable></term>
<listitem>
<para>Sets, for the duration of the command, the value of
a runtime configuration
- option. <replaceable>FILE</replaceable>
+ option. <replaceable>CONFSPEC</replaceable> is a string
+ which specifies the configuration option namespace, name
+ and value that you'd like to assign, formatted as
+
<replaceable>FILE</replaceable>:<replaceable>SECTION</replaceable>:<replaceable>OPTION</replaceable>=[<replaceable>VALUE</replaceable>].
+ In this syntax, <replaceable>FILE</replaceable>
and <replaceable>SECTION</replaceable> are the runtime
configuration file (either <literal>config</literal>
or <literal>servers</literal>) and the section thereof,
More information about the svnbook-dev
mailing list