In this section, we will discuss the specific runtime configuration options that Subversion currently supports.
The servers file
contains Subversion configuration options related to the network
layers. There are two special section names in this file—groups
and global
. The groups
section is
essentially a cross-reference table. The keys in this section are the
names of other sections in the file; their values are
globs—textual tokens that possibly contain wildcard characters—that
are compared against the hostnames of the machine to which Subversion
requests are sent:
[groups] beanie-babies = *.red-bean.com collabnet = svn.collab.net [beanie-babies] ... [collabnet] ...
When Subversion is used over a network, it attempts to match the
name of the server it is trying to reach with a group name under the
groups
section. If a match is made,
Subversion then looks for a section in the servers file whose name is the matched
group’s name. From that section, it reads the actual network
configuration settings.
The global
section contains
the settings that are meant for all of the servers not matched by one
of the globs under the groups
section. The options available in this section are exactly the same as
those that are valid for the other server sections in the file
(except, of course, the special groups
section), and are as follows:
http-proxy-exceptions
This specifies a comma-separated list of patterns for repository hostnames that should be accessed directly, without using the proxy machine. The pattern syntax is the same as is used in the Unix shell for filenames. A repository hostname matching any of these patterns will not be proxied.
http-proxy-host
This specifies the hostname of the proxy computer through which your HTTP-based Subversion requests must pass. It defaults to an empty value, which means that Subversion will not attempt to route HTTP requests through a proxy computer and will instead attempt to contact the destination machine directly.
http-proxy-port
This specifies the port number on the proxy host to use. It defaults to an empty value.
http-proxy-username
This specifies the username to supply to the proxy machine. It defaults to an empty value.
http-proxy-password
This specifies the password to supply to the proxy machine. It defaults to an empty value.
http-timeout
This specifies the amount of time, in seconds, to wait for a
server response. If you experience problems with a slow network
connection causing Subversion operations to time out, you should
increase the value of this option. The default value is 0
, which instructs the underlying HTTP
library, Neon, to use its default timeout setting.
http-compression
This specifies whether Subversion should attempt to compress
network requests made to DAV-ready servers. The default value is
yes
(though compression will
occur only if that capability is compiled into the network
layer). Set this to no
to
disable compression, such as when debugging network
transmissions.
http-library
Subversion provides a pair of repository access modules that
understand its WebDAV network protocol. The original one, which
shipped with Subversion 1.0, is libsvn_ra_neon
(though back then it
was called libsvn_ra_dav
).
Newer Subversion versions also provide libsvn_ra_serf
, which uses a different
underlying implementation and aims to support some of the newer
HTTP concepts.
At this point, libsvn_ra_serf
is still considered
experimental, though it appears to work in the common cases
quite well. To encourage experimentation, Subversion provides
the http-library
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—neon
or
serf
.
http-auth-types
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 basic
, digest
, and negotiate
.
neon-debug-mask
This is an integer mask that the underlying HTTP library,
Neon, uses for choosing what type of debugging output to yield.
The default value is 0
, which
will silence all debugging output. For more information about
how Subversion makes use of Neon, see Chapter 8.
ssl-authority-files
This is a semicolon-delimited list of paths to files containing certificates of the certificate authorities (or CAs) that are accepted by the Subversion client when accessing the repository over HTTPS.
ssl-trust-default-ca
Set this variable to yes
if you want Subversion to
automatically trust the set of default CAs that ship with
OpenSSL.
ssl-client-cert-file
If a host (or set of hosts) requires an SSL client certificate, you’ll normally be prompted for a path to your certificate. By setting this variable to that same path, Subversion will be able to find your client certificate automatically without prompting you. There’s no standard place to store your certificate on disk; Subversion will grab it from any path you specify.
ssl-client-cert-password
If your SSL client certificate file is encrypted by a passphrase, Subversion will prompt you for the passphrase whenever the certificate is used. If you find this annoying (and don’t mind storing the password in the servers file), you can set this variable to the certificate’s passphrase. You won’t be prompted anymore.
The config file contains the rest of the currently available Subversion runtime options—those not related to networking. Only a few options are in use as of this writing, but they are again grouped into sections in expectation of future additions.
The auth
section contains settings related to Subversion’s authentication
and authorization against the repository. It contains the
following:
store-passwords
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 yes
. Set this to no
to disable this on-disk password
caching. You can override this option for a single instance of
the svn command using the
--no-auth-cache
command-line parameter (for those
subcommands that support it). For more information, see Client Credentials Caching.
store-auth-creds
This setting is the same as store-passwords
, except that it
enables or disables on-disk caching of all
authentication information: usernames, passwords, server certificates, and any other types
of cacheable credentials.
The helpers
section controls
which external applications Subversion uses to accomplish its tasks.
Valid options in this section are:
editor-cmd
This specifies the program that Subversion will use to query the user for certain types of textual metadata or when interactively resolving conflicts. See Using External Editors for more details on using external text editors with Subversion.
diff-cmd
This specifies the absolute path of a differencing program, used when Subversion generates “diff” output (such as when using the svn diff command). By default, Subversion uses an internal differencing library—setting this option will cause it to perform this task using an external program. See Using External Differencing and Merge Tools for more details on using such programs.
diff3-cmd
This specifies the absolute path of a three-way differencing program. Subversion uses this program to merge changes made by the user with those received from the repository. By default, Subversion uses an internal differencing library—setting this option will cause it to perform this task using an external program. See Using External Differencing and Merge Tools for more details on using such programs.
diff3-has-program-arg
This flag should be set to true
if the program specified by the
diff3-cmd
option accepts a
--diff-program
command-line parameter.
merge-tool-cmd
This specifies the program that Subversion will use to perform three-way merge operations on your versioned files. See Using External Differencing and Merge Tools for more details on using such programs.
The tunnels
section
allows you to define new tunnel schemes for use with
svnserve and svn://
client connections. For more details,
see Tunneling over SSH.
The miscellany
section is
where everything that doesn’t belong elsewhere winds up.[50] In this section, you can find:
global-ignores
When running the svn
status command, Subversion lists unversioned files and
directories along with the versioned ones, annotating them with
a ?
character (see See an overview of your changes). Sometimes, it can
be annoying to see uninteresting, unversioned items—for example,
object files that result from a program’s compilation—in this
display. The global-ignores
option is a list of whitespace-delimited globs that describe the
names of files and directories that Subversion should not
display unless they are versioned. The default value is *.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#*
.DS_Store
.
As well as svn status,
the svn add and svn import commands also ignore files
that match the list when they are scanning a directory. You can
override this behavior for a single instance of any of these
commands by explicitly specifying the filename, or by using the
--no-ignore
command-line flag.
For information on finer-grained control of ignored items, see Ignoring Unversioned Items.
enable-auto-props
This instructs Subversion to automatically set properties on
newly added or imported files. The default value is no
, so set this to yes
to enable this feature. The
auto-props
section of this
file specifies which properties are to be set on which
files.
log-encoding
This variable sets the default character set encoding for
commit log messages. It’s a permanent form of the
--encoding
option (see svn Options). The Subversion repository stores
log messages in UTF-8 and assumes that your log message is
written using your operating system’s native locale. You should
specify a different encoding if your commit messages are written
in any other encoding.
use-commit-times
Normally your working copy files have timestamps that reflect the last time they were touched by any process, whether your own editor or some svn 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.
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 svn export command always places these
“last-commit timestamps” on trees that it produces.
By setting this config variable to yes
, the svn
checkout, svn
update, svn switch, and svn revert commands will also set
last-commit timestamps on files that they touch.
mime-types-file
This option, new to Subversion 1.5, specifies the path of a MIME types mapping file, such as the mime.types file provided by the Apache HTTP Server. Subversion uses this file to assign MIME types to newly added or imported files. See Automatic Property Setting and File Content Type for more about Subversion’s detection and use of file content types.
preserved-conflict-file-exts
The value of this option is a space-delimited list of file extensions that Subversion should preserve when generating conflict filenames. By default, the list is empty. This option is new to Subversion 1.5.
When Subversion detects conflicting file content changes,
it defers resolution of those conflicts to the user. To assist
in the resolution, Subversion keeps pristine copies of the
various competing versions of the file in the working copy. By
default, those conflict files have names constructed by
appending to the original filename a custom extension such as
.mine or .REV
(where REV
is a revision number). A
mild annoyance with this naming scheme is that on operating
systems where a file’s extension determines the default
application used to open and edit that file, appending a custom
extension prevents the file from being easily opened by its
native application. For example, if the file ReleaseNotes.pdf was conflicted, the
conflict files might be named ReleaseNotes.pdf.mine or ReleaseNotes.pdf.r4231. While your
system might be configured to use Adobe’s Acrobat Reader to open
files whose extensions are .pdf, there probably isn’t an
application configured on your system to open all files whose
extensions are .r4231.
You can fix this annoyance by using this configuration
option, though. For files with one of the specified extensions,
Subversion will append to the conflict file names the custom
extension just as before, but then also reappend the file’s
original extension. Using the previous example, and assuming
that pdf
is one of the
extensions configured in
this list thereof, the conflict files generated for ReleaseNotes.pdf
would instead be named ReleaseNotes.pdf.mine.pdf and
ReleaseNotes.pdf.r4231.pdf.
Because each file ends in .pdf, the correct default application
will be used to view them.
interactive-conflicts
This is a Boolean option that specifies whether Subversion should try to
resolve conflicts interactively. If its value is yes
(the default value), Subversion
will prompt the user for how to handle conflicts in the manner
demonstrated in the section Resolve Conflicts (Merging Others’ Changes). Otherwise, it will simply
flag the conflict and continue its operation, postponing
resolution to a later time.
no-unlock
This Boolean option corresponds to svn commit’s
--no-unlock
option, which tells Subversion not
to release locks on files you’ve just committed. If this runtime
option is set to yes
, Subversion will never release
locks automatically, leaving you to run svn unlock explicitly. It defaults to
no
.
The auto-props
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 PATTERN = PROPNAME=VALUE[;PROPNAME=VALUE
...]
, where PATTERN
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 “override” another. You can find several
examples of auto-props usage in the config file. Lastly, don’t forget to set
enable-auto-props
to yes
in the miscellany
section if you want to enable
auto-props.