[svnbook] r3957 committed - * src/en/book/ch07-customizing-svn.xml...
svnbook at googlecode.com
svnbook at googlecode.com
Fri Aug 5 09:44:12 CDT 2011
Revision: 3957
Author: cmpilato at gmail.com
Date: Fri Aug 5 07:43:09 2011
Log: * src/en/book/ch07-customizing-svn.xml
Read-thru edits. Adds coverage of some of the newer runtime config
parameters.
http://code.google.com/p/svnbook/source/detail?r=3957
Modified:
/trunk/src/en/book/ch07-customizing-svn.xml
=======================================
--- /trunk/src/en/book/ch07-customizing-svn.xml Tue Jul 26 10:03:35 2011
+++ /trunk/src/en/book/ch07-customizing-svn.xml Fri Aug 5 07:43:09 2011
@@ -35,8 +35,8 @@
a two-tiered hierarchy of option names and their values.
Usually, this boils down to a special directory that contains
<firstterm>configuration files</firstterm> (the first tier),
- which are just text files in standard INI format (with
- <quote>sections</quote> providing the second tier). You can
+ which are just text files in standard INI format where
+ <quote>sections</quote> provide the second tier. You can
easily edit these files using your favorite text editor (such as
Emacs or vi), and they contain directives read by the client to
determine which of several optional behaviors the user
@@ -192,52 +192,64 @@
[HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion\Servers\groups]
[HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion\Servers\global]
+"#http-auth-types"="basic;digest;negotiate"
+"#http-compression"="yes"
+"#http-library"=""
+"#http-proxy-exceptions"=""
"#http-proxy-host"=""
+"#http-proxy-password"=""
"#http-proxy-port"=""
"#http-proxy-username"=""
-"#http-proxy-password"=""
-"#http-proxy-exceptions"=""
"#http-timeout"="0"
-"#http-compression"="yes"
"#neon-debug-mask"=""
"#ssl-authority-files"=""
-"#ssl-trust-default-ca"=""
"#ssl-client-cert-file"=""
"#ssl-client-cert-password"=""
+"#ssl-pkcs11-provider"=""
+"#ssl-trust-default-ca"=""
+"#store-auth-creds"="yes"
+"#store-passwords"="yes"
+"#store-plaintext-passwords"="ask"
+"#store-ssl-client-cert-pp"="yes"
+"#store-ssl-client-cert-pp-plaintext"="ask"
+"#username"=""
[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\auth]
-"#store-passwords"="yes"
-"#store-auth-creds"="yes"
+"#password-stores"="windows-cryptoapi"
[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\helpers]
-"#editor-cmd"="notepad"
"#diff-cmd"=""
"#diff3-cmd"=""
"#diff3-has-program-arg"=""
+"#editor-cmd"="notepad"
+"#merge-tool-cmd"=""
[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\tunnels]
[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\miscellany]
-"#global-ignores"="*.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#* .DS_Store"
+"#enable-auto-props"="no"
+"#global-ignores"="*.o *.lo *.la *.al .libs *.so *.so.[0-9]* *.a *.pyc
*.pyo *.rej *~ #*# .#* .*.swp .DS_Store"
+"#interactive-conflicts"="yes"
"#log-encoding"=""
-"#use-commit-times"=""
-"#no-unlock"=""
-"#enable-auto-props"=""
+"#mime-types-file"=""
+"#no-unlock"="no"
+"#preserved-conflict-file-exts"="doc ppt xls od?"
+"#use-commit-times"="no"
[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\auto-props]
</programlisting>
</example>
- <para>The previous example shows the contents of a
- <filename>.reg</filename> file, which contains some of the most
- commonly used configuration options and their default values.
- Note the presence of both system-wide (for network
- proxy-related options) and per-user settings (editor programs
- and password storage, among others). Also note that all the
- options are effectively commented out. You need only to
- remove the hash (<literal>#</literal>) character from the
- beginning of the option names and set the values as you
- desire.</para>
+ <para><xref linkend="svn.advanced.confarea.windows-registry.ex-1"/>
+ shows the contents of a <filename>.reg</filename> file, which
+ contains some of the most commonly used configuration options
+ and their default values. Note the presence of both
+ system-wide (for network proxy-related options) and per-user
+ settings (editor programs and password storage, among others).
+ Also note that all the options are effectively commented out.
+ You need only to remove the hash (<literal>#</literal>)
+ character from the beginning of the option names and set the
+ values as you desire.</para>
</sect2>
@@ -300,6 +312,63 @@
<variablelist>
<varlistentry>
+ <term><literal>http-auth-types</literal></term>
+ <listitem>
+ <para>This is a semicolon-delimited list of HTTP
+ authentication types which the client will deem
+ acceptable. Valid types
+ are <literal>basic</literal>, <literal>digest</literal>,
+ and <literal>negotiate</literal>, with the default
+ behavior being acceptance of any these authentication
+ types. A client which insists on not transmitting
+ authentication credentials in cleartext might, for
+ example, be configured such that the value of this
+ option is
+ <literal>digest;negotiate</literal>—omitting
+ <literal>basic</literal> from the list. (Note that
+ this setting is only honored by Subversion's
+ Neon-based HTTP provider module.)</para>
+ <!-- ### TODO: Subversion 1.7 exposed this to Serf, too,
+ and with an additional 'ntlm' auth type. -->
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>http-compression</literal></term>
+ <listitem>
+ <para>This specifies whether Subversion should
+ attempt to compress network requests made to DAV-ready
+ servers. The default value is <literal>yes</literal>
+ (though compression will occur only if that capability
+ is compiled into the network layer). Set this to
+ <literal>no</literal> to disable compression, such as
+ when debugging network transmissions.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>http-library</literal></term>
+ <listitem>
+ <para>Subversion provides a pair of repository access
+ modules that understand its WebDAV network protocol.
+ The original one, which shipped with Subversion 1.0, is
+ <literal>libsvn_ra_neon</literal> (though back then it
+ was called <literal>libsvn_ra_dav</literal>). Newer
+ Subversion versions also provide
+ <literal>libsvn_ra_serf</literal>, which uses a
+ different underlying implementation and aims to
+ support some of the newer HTTP concepts.</para>
+
+ <para>At this point, <literal>libsvn_ra_serf</literal>
+ is still considered experimental, though it appears to
+ work in the common cases quite well. To encourage
+ experimentation, Subversion provides the
+ <literal>http-library</literal> runtime configuration
+ option to allow users to specify (generally, or in a
+ per-server-group fashion) which WebDAV access module
+ they'd prefer to use—<literal>neon</literal> or
+ <literal>serf</literal>.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
<term><literal>http-proxy-exceptions</literal></term>
<listitem>
<para>This specifies a comma-separated list of patterns
@@ -320,6 +389,13 @@
through a proxy computer, and will instead attempt to
contact the destination machine directly.</para>
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>http-proxy-password</literal></term>
+ <listitem>
+ <para>This specifies the password to supply to the proxy
+ machine. It defaults to an empty value.</para>
+ </listitem>
</varlistentry>
<varlistentry>
<term><literal>http-proxy-port</literal></term>
@@ -334,13 +410,6 @@
<para>This specifies the username to supply to the proxy
machine. It defaults to an empty value.</para>
</listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>http-proxy-password</literal></term>
- <listitem>
- <para>This specifies the password to supply to the proxy
- machine. It defaults to an empty value.</para>
- </listitem>
</varlistentry>
<varlistentry>
<term><literal>http-timeout</literal></term>
@@ -354,53 +423,6 @@
HTTP library, Neon, to use its default timeout
setting.</para>
</listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>http-compression</literal></term>
- <listitem>
- <para>This specifies whether Subversion should
- attempt to compress network requests made to DAV-ready
- servers. The default value is <literal>yes</literal>
- (though compression will occur only if that capability
- is compiled into the network layer). Set this to
- <literal>no</literal> to disable compression, such as
- when debugging network transmissions.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>http-library</literal></term>
- <listitem>
- <para>Subversion provides a pair of repository access
- modules that understand its WebDAV network protocol.
- The original one, which shipped with Subversion 1.0, is
- <literal>libsvn_ra_neon</literal> (though back then it
- was called <literal>libsvn_ra_dav</literal>). Newer
- Subversion versions also provide
- <literal>libsvn_ra_serf</literal>, which uses a
- different underlying implementation and aims to
- support some of the newer HTTP concepts.</para>
-
- <para>At this point, <literal>libsvn_ra_serf</literal>
- is still considered experimental, though it appears to
- work in the common cases quite well. To encourage
- experimentation, Subversion provides the
- <literal>http-library</literal> runtime configuration
- option to allow users to specify (generally, or in a
- per-server-group fashion) which WebDAV access module
- they'd prefer to use—<literal>neon</literal> or
- <literal>serf</literal>.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>http-auth-types</literal></term>
- <listitem>
- <para>This option is a semicolon-delimited list of
- authentication types supported by the Neon-based
- WebDAV repository access modules. Valid members of
- this list are <literal>basic</literal>,
- <literal>digest</literal>, and
- <literal>negotiate</literal>.</para>
- </listitem>
</varlistentry>
<varlistentry>
<term><literal>neon-debug-mask</literal></term>
@@ -422,14 +444,6 @@
are accepted by the Subversion client when accessing the
repository over HTTPS.</para>
</listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>ssl-trust-default-ca</literal></term>
- <listitem>
- <para>Set this variable to <literal>yes</literal> if you
- want Subversion to automatically trust the set of
- default CAs that ship with OpenSSL.</para>
- </listitem>
</varlistentry>
<varlistentry>
<term><literal>ssl-client-cert-file</literal></term>
@@ -457,23 +471,21 @@
</listitem>
</varlistentry>
<varlistentry>
- <term><literal>store-passwords</literal></term>
+ <term><literal>ssl-pkcs11-provider</literal></term>
<listitem>
- <para>This instructs Subversion to cache, or not to
- cache, passwords that are supplied by the user in
- response to server authentication challenges. The
- default value is <literal>yes</literal>. Set this to
- <literal>no</literal> to disable this on-disk password
- caching. You can override this option for a single
- instance of the <command>svn</command> command using
- the <option>--no-auth-cache</option> command-line
- parameter (for those subcommands that support it).
- For more information regarding that, see
- <xref linkend="svn.serverconfig.netmodel.credcache"/>.
Note that regardless of how this option is
- configured, Subversion will not store passwords in
- plaintext unless
- the <literal>store-plaintext-passwords</literal>
- option is also set to <literal>yes</literal>. </para>
+ <para>The value of this option is the name of the
+ PKCS#11 provider from which an SSL client certificate
+ will be drawn (if the server asks for one). This
+ setting is only honored by Subversion's Neon-based
+ HTTP provider module.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ssl-trust-default-ca</literal></term>
+ <listitem>
+ <para>Set this variable to <literal>yes</literal> if you
+ want Subversion to automatically trust the set of
+ default CAs that ship with OpenSSL.</para>
</listitem>
</varlistentry>
<varlistentry>
@@ -486,6 +498,26 @@
usernames, passwords, server certificates, and any
other types of cacheable credentials.</para>
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>store-passwords</literal></term>
+ <listitem>
+ <para>This instructs Subversion to cache, or not to
+ cache, passwords that are supplied by the user in
+ response to server authentication challenges. The
+ default value is <literal>yes</literal>. Set this to
+ <literal>no</literal> to disable this on-disk password
+ caching. You can override this option for a single
+ instance of the <command>svn</command> command using
+ the <option>--no-auth-cache</option> command-line
+ parameter (for those subcommands that support it).
+ For more information regarding that, see
+ <xref linkend="svn.serverconfig.netmodel.credcache"/>.
+ Note that regardless of how this option is configured,
+ Subversion will not store passwords in plaintext
+ unless the <literal>store-plaintext-passwords</literal>
+ option is also set to <literal>yes</literal>.</para>
+ </listitem>
</varlistentry>
<varlistentry>
<term><literal>store-plaintext-passwords</literal></term>
@@ -503,6 +535,34 @@
<emphasis>new</emphasis> password is about to be added to
the <filename>~/.subversion/auth/</filename> caching area.
</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>store-ssl-client-cert-pp</literal></term>
+ <listitem>
+ <para>This option controls whether Subversion will cache
+ SSL client certificate passphrases provided by the
+ user. Its value defaults to <literal>yes</literal>.
+ Set this to <literal>no</literal> to disable this
+ passphrase caching.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+
<term><literal>store-ssl-client-cert-pp-plaintext</literal></term>
+ <listitem>
+ <para>This option controls whether Subversion, when
+ attempting to cache an SSL client certificate
+ passphrase, will be allowed to do so using its on-disk
+ plaintext storage mechanism. The default value of
+ this option is <literal>ask</literal>, which causes
+ the Subversion client to ask you each time a
+ <emphasis>new</emphasis> client certificate passphrase
+ is about to be added to
+ the <filename>~/.subversion/auth/</filename> caching
+ area. Set this option's value
+ to <literal>yes</literal> or <literal>no</literal> to
+ indicate your preference and avoid related
+ prompts.</para>
</listitem>
</varlistentry>
</variablelist>
@@ -571,17 +631,6 @@
<variablelist>
<varlistentry>
- <term><literal>editor-cmd</literal></term>
- <listitem>
- <para>This specifies the program Subversion will use to
- query the user for certain types of textual metadata
- or when interactively resolving conflicts. See
- <xref linkend="svn.advanced.externaleditors"/> for
- more details on using external text editors with
- Subversion.</para>
- </listitem>
- </varlistentry>
- <varlistentry>
<term><literal>diff-cmd</literal></term>
<listitem>
<para>This specifies the absolute path of a differencing
@@ -618,6 +667,17 @@
<option>--diff-program</option> command-line
parameter.</para>
</listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>editor-cmd</literal></term>
+ <listitem>
+ <para>This specifies the program Subversion will use to
+ query the user for certain types of textual metadata
+ or when interactively resolving conflicts. See
+ <xref linkend="svn.advanced.externaleditors"/> for
+ more details on using external text editors with
+ Subversion.</para>
+ </listitem>
</varlistentry>
<varlistentry>
<term><literal>merge-tool-cmd</literal></term>
@@ -645,6 +705,17 @@
<variablelist>
<varlistentry>
+ <term><literal>enable-auto-props</literal></term>
+ <listitem>
+ <para>This instructs Subversion to automatically set
+ properties on newly added or imported files. The
+ default value is <literal>no</literal>, so set this to
+ <literal>yes</literal> to enable this feature.
+ The <literal>[auto-props]</literal> section of this file
+ specifies which properties are to be set on which
files.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
<term><literal>global-ignores</literal></term>
<listitem>
<para>When running the <command>svn status</command>
@@ -660,8 +731,8 @@
files and directories that Subversion should not
display unless they are versioned. The default value
is <literal>*.o *.lo *.la *.al .libs *.so *.so.[0-9]*
- *.a *.pyc *.pyo *.rej *~ #*# .#* .*.swp .DS_Store
- </literal>.</para>
+ *.a *.pyc *.pyo *.rej *~ #*# .#* .*.swp
+ .DS_Store</literal>.</para>
<para>As well as <command>svn status</command>, the
<command>svn add</command> and <command>svn
import</command>
@@ -676,19 +747,20 @@
<xref linkend="svn.advanced.props.special.ignore"
/>.</para>
</listitem>
</varlistentry>
-
<varlistentry>
- <term><literal>enable-auto-props</literal></term>
+ <term><literal>interactive-conflicts</literal></term>
<listitem>
- <para>This instructs Subversion to automatically set
- properties on newly added or imported files. The
- default value is <literal>no</literal>, so set this to
- <literal>yes</literal> to enable this feature.
- The <literal>[auto-props]</literal> section of this file
- specifies which properties are to be set on which
files.</para>
- </listitem>
+ <para>This is a Boolean option that specifies whether
+ Subversion should try to resolve conflicts
+ interactively. If its value is <literal>yes</literal>
+ (which is the default value), Subversion will prompt
+ the user for how to handle conflicts in the manner
+ demonstrated in <xref linkend="svn.tour.cycle.resolve"
+ />. Otherwise, it will simply flag the conflict and
+ continue its operation, postponing resolution to a later
+ time.</para>
+ </listitem>
</varlistentry>
-
<varlistentry>
<term><literal>log-encoding</literal></term>
<listitem>
@@ -703,33 +775,6 @@
in any other encoding.</para>
</listitem>
</varlistentry>
-
- <varlistentry>
- <term><literal>use-commit-times</literal></term>
- <listitem>
- <para>Normally your working copy files have timestamps
- that reflect the last time they were touched by any
- process, whether your own editor or some
- <command>svn</command> subcommand. This is generally
- convenient for people developing software, because
- build systems often look at timestamps as a way of
- deciding which files need to be recompiled.</para>
-
- <para>In other situations, however, it's sometimes nice
- for the working copy files to have timestamps that
- reflect the last time they were changed in the
- repository. The <command>svn export</command> command
- always places these <quote>last-commit
- timestamps</quote> on trees that it produces. By
- setting this config variable to
- <literal>yes</literal>, the <command>svn
- checkout</command>, <command>svn update</command>,
- <command>svn switch</command>, and <command>svn
- revert</command> commands will also set last-commit
- timestamps on files that they touch.</para>
- </listitem>
- </varlistentry>
-
<varlistentry>
<term><literal>mime-types-file</literal></term>
<listitem>
@@ -744,7 +789,19 @@
file content types.</para>
</listitem>
</varlistentry>
-
+ <varlistentry>
+ <term><literal>no-unlock</literal></term>
+ <listitem>
+ <para>This Boolean option corresponds to <command>svn
+ commit</command>'s <option>--no-unlock</option>
+ option, which tells Subversion not to release locks on
+ files you've just committed. If this runtime option
+ is set to <literal>yes</literal>, Subversion will
+ never release locks automatically, leaving you to run
+ <command>svn unlock</command> explicitly. It defaults
+ to <literal>no</literal>.</para>
+ </listitem>
+ </varlistentry>
<varlistentry>
<term><literal>preserved-conflict-file-exts</literal></term>
<listitem>
@@ -798,54 +855,48 @@
application will be used to view them.</para>
</listitem>
</varlistentry>
-
<varlistentry>
- <term><literal>interactive-conflicts</literal></term>
- <listitem>
- <para>This is a Boolean option that specifies whether
- Subversion should try to resolve conflicts
- interactively. If its value is <literal>yes</literal>
- (which is the default value), Subversion will prompt
- the user for how to handle conflicts in the manner
- demonstrated in <xref linkend="svn.tour.cycle.resolve"
- />. Otherwise, it will simply flag the conflict and
- continue its operation, postponing resolution to a later
- time.</para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><literal>no-unlock</literal></term>
- <listitem>
- <para>This Boolean option corresponds to <command>svn
- commit</command>'s <option>--no-unlock</option>
- option, which tells Subversion not to release locks on
- files you've just committed. If this runtime option
- is set to <literal>yes</literal>, Subversion will
- never release locks automatically, leaving you to run
- <command>svn unlock</command> explicitly. It defaults
- to <literal>no</literal>.</para>
-
- </listitem>
+ <term><literal>use-commit-times</literal></term>
+ <listitem>
+ <para>Normally your working copy files have timestamps
+ that reflect the last time they were touched by any
+ process, whether your own editor or some
+ <command>svn</command> subcommand. This is generally
+ convenient for people developing software, because
+ build systems often look at timestamps as a way of
+ deciding which files need to be recompiled.</para>
+
+ <para>In other situations, however, it's sometimes nice
+ for the working copy files to have timestamps that
+ reflect the last time they were changed in the
+ repository. The <command>svn export</command> command
+ always places these <quote>last-commit
+ timestamps</quote> on trees that it produces. By
+ setting this config variable to
+ <literal>yes</literal>, the <command>svn
+ checkout</command>, <command>svn update</command>,
+ <command>svn switch</command>, and <command>svn
+ revert</command> commands will also set last-commit
+ timestamps on files that they touch.</para>
+ </listitem>
</varlistentry>
-
</variablelist>
- <para>The <literal>[auto-props]</literal> section controls
- the Subversion client's ability to automatically set
- properties on files when they are added or imported.
- It contains any number of key-value pairs in the
- format <literal>PATTERN = PROPNAME=VALUE[;PROPNAME=VALUE
- ...]</literal>, where <literal>PATTERN</literal> is a file
- pattern that matches one or more filenames and the rest of
- the line is a semicolon-delimited set of property
- assignments. Multiple matches
- on a file will result in multiple propsets for that
- file; however, there is no guarantee that auto-props
- will be applied in the order in which they are listed
- in the config file, so you can't have one rule
- <quote>override</quote> another. You can find several
- examples of auto-props usage in the
+ <para>The <literal>[auto-props]</literal> section controls the
+ Subversion client's ability to automatically set properties
+ on files when they are added or imported. It contains any
+ number of key-value pairs in the
+ format <literal><replaceable>PATTERN</replaceable>
+ =
<replaceable>PROPNAME</replaceable>=<replaceable>VALUE</replaceable>[;<replaceable>PROPNAME</replaceable>=<replaceable>VALUE</replaceable>
+ ...]</literal>, where <replaceable>PATTERN</replaceable> is
+ a file pattern that matches one or more filenames and the
+ rest of the line is a semicolon-delimited set of property
+ assignments. Multiple matches on a file will result in
+ multiple propsets for that file; however, there is no
+ guarantee that auto-props will be applied in the order in
+ which they are listed in the config file, so you can't have
+ one rule <quote>override</quote> another. You can find
+ several examples of auto-props usage in the
<filename>config</filename> file. Lastly, don't
forget to set <literal>enable-auto-props</literal> to
<literal>yes</literal> in the <literal>miscellany</literal>
More information about the svnbook-dev
mailing list