Subversion provides many optional behaviors that the user can control. Many of these options are of the kind that a user would wish to apply to all Subversion operations. So, rather than forcing users to remember command-line arguments for specifying these options and to use them for every operation they perform, Subversion uses configuration files, segregated into a Subversion configuration area.
The Subversion runtime configuration area is a two-tiered hierarchy of option names and their values. Usually, this boils down to a special directory that contains configuration files (the first tier), which are just text files in standard INI format where “sections” 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 prefers.
The first time the svn command-line
client is executed, it creates a per-user configuration area.
On Unix-like systems, this area appears as a directory
named .subversion in the user's home
directory. On Win32 systems, Subversion creates a folder
named Subversion, typically inside
the Application Data area of the user's
profile directory (which, by the way, is usually a hidden
directory). However, on this platform, the exact location
differs from system to system and is dictated by the Windows
Registry.[74]
We will refer to the per-user configuration area using its
Unix name, .subversion.
In addition to the per-user configuration area, Subversion
also recognizes the existence of a system-wide configuration
area. This gives system administrators the ability to
establish defaults for all users on a given machine. Note
that the system-wide configuration area alone does not dictate
mandatory policy—the settings in the per-user
configuration area override those in the system-wide one, and
command-line arguments supplied to the svn
program have the final word on behavior. On Unix-like
platforms, the system-wide configuration area is
expected to be the /etc/subversion
directory; on Windows machines, it looks for a
Subversion directory inside the common
Application Data location (again, as
specified by the Windows Registry). Unlike the per-user
case, the svn program does not attempt
to create the system-wide configuration area.
The per-user configuration area currently contains three
files—two configuration files (config and
servers), and a README.txt
file, which describes the INI format. At the time of their
creation, the files contain default values for each of the
supported Subversion options, mostly commented out and grouped
with textual descriptions about how the values for the key
affect Subversion's behavior. To change a certain behavior,
you need only to load the appropriate configuration file into
a text editor, and to modify the desired option's value. If at
any time you wish to have the default configuration settings
restored, you can simply remove (or rename) your configuration
directory and then run some innocuous svn
command, such as svn --version. A new
configuration directory with the default contents will be
created.
Subversion also allows you to override individual
configuration option values at the command line via
the --config-option option, which is
especially useful if you need to make a (very) temporary
change in behavior. For more about this option's proper
usage, see svn Options.
The per-user configuration area also contains a cache of
authentication data. The auth directory
holds a set of subdirectories that contain pieces of cached
information used by Subversion's various supported
authentication methods. This directory is created in such a
way that only the user herself has permission to read its
contents.
In addition to the usual INI-based configuration area, Subversion clients running on Windows platforms may also use the Windows Registry to hold the configuration data. The option names and their values are the same as in the INI files. The “file/section” hierarchy is preserved as well, though addressed in a slightly different fashion—in this schema, files and sections are just levels in the Registry key tree.
Subversion looks for system-wide configuration values
under the
HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion
key. For example, the global-ignores option,
which is in the miscellany section of the
config file, would be found at
HKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion\Config\Miscellany\global-ignores.
Per-user configuration values should be stored under
HKEY_CURRENT_USER\Software\Tigris.org\Subversion.
Registry-based configuration options are parsed before their file-based counterparts, so they are overridden by values found in the configuration files. In other words, Subversion looks for configuration information in the following locations on a Windows system; lower-numbered locations take precedence over higher-numbered locations:
Command-line options
The per-user INI files
The per-user Registry values
The system-wide INI files
The system-wide Registry values
Also, the Windows Registry doesn't really support the
notion of something being “commented out.”
However, Subversion will ignore any option key whose name
begins with a hash (#) character. This
allows you to effectively comment out a Subversion option
without deleting the entire key from the Registry, obviously
simplifying the process of restoring that option.
The svn command-line client never
attempts to write to the Windows Registry and will not attempt
to create a default configuration area there. You can create
the keys you need using the REGEDIT
program. Alternatively, you can create a
.reg file (such as the one in Example 7.1, “Sample registration entries (.reg) file”), and
then double-click on that file's icon in the Explorer shell,
which will cause the data to be merged into your
Registry.
Example 7.1. Sample registration entries (.reg) file
REGEDIT4 [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-timeout"="0" "#neon-debug-mask"="" "#ssl-authority-files"="" "#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] "#password-stores"="windows-cryptoapi" [HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\helpers] "#diff-cmd"="" "#diff-extensions"="-u" "#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] "#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"="" "#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]
Example 7.1, “Sample registration entries (.reg) file”
shows the contents of a .reg 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 (#)
character from the beginning of the option names and set the
values as you desire.
In this section, we will discuss the specific runtime configuration options that Subversion currently supports.
The config file contains the rest
of the currently available Subversion runtime
options—those not related to networking. There are
only a few options 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:
password-storesThis comma-delimited list specifies which (if any) system-provided password stores Subversion should attempt to use when saving and retrieving cached authentication credentials, and in what order Subversion should prefer them. The default value is
gnome-keyring, kwallet, keychain, gpg-agent, windows-crypto-api, representing the GNOME Keyring, KDE Wallet, Mac OS X Keychain, GnuPG Agent, and Microsoft Windows cryptography API, respectively. Listed stores which are not available on the system are ignored.store-passwordsThis option has been deprecated from the
configfile. It now lives as a per-server configuration item in theserversconfiguration area. See the section called “Per-server configuration” for details.store-auth-credsThis option has been deprecated from the
configfile. It now lives as a per-server configuration item in theserversconfiguration area. See the section called “Per-server configuration” for details.
The [helpers] section controls which
external applications Subversion uses to accomplish its
tasks. Valid options in this section are:
diff-cmdThis 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 the section called “Using External Differencing and Merge Tools” for more details on using such programs.
diff-extensionsLike the
--extensions(-x) command-line option, this specifies additional options passed to the file content differencing engine. The set of meaningful extension options differs depending on whether the client is using Subversion's internal differencing engine or an external mechanism. See the output ofsvn help difffor details. The default value for this option is-u.diff3-cmdThis 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 the section called “Using External Differencing and Merge Tools” for more details on using such programs.
diff3-has-program-argThis flag should be set to
trueif the program specified by thediff3-cmdoption accepts a--diff-programcommand-line parameter.editor-cmdThis specifies the program Subversion will use to query the user for certain types of textual metadata or when interactively resolving conflicts. See the section called “Using External Editors” for more details on using external text editors with Subversion.
merge-tool-cmdThis specifies the program that Subversion will use to perform three-way merge operations on your versioned files. See the section called “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 the section called “Tunneling over SSH”.
The [miscellany] section is where
everything that doesn't belong elsewhere winds
up.[75] In this section, you can
find:
enable-auto-propsThis instructs Subversion to automatically set properties on newly added or imported files. The default value is
no, so set this toyesto enable this feature. The[auto-props]section of this file specifies which properties are to be set on which files.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 the section called “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. Theglobal-ignoresoption 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 *.al .libs *.so *.so.[0-9]* *.a *.pyc *.pyo *.rej *~ #*# .#* .*.swp .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-ignorecommand-line flag.For information on finer-grained control of ignored items, see the section called “Ignoring Unversioned Items”.
interactive-conflictsThis is a Boolean option that specifies whether Subversion should try to resolve conflicts interactively. If its value is
yes(which is the default value), Subversion will prompt the user for how to handle conflicts in the manner demonstrated in the section called “Resolve Any Conflicts”. Otherwise, it will simply flag the conflict and continue its operation, postponing resolution to a later time.log-encodingThis variable sets the default character set encoding for commit log messages. It's a permanent form of the
--encodingoption (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.mime-types-fileThis option, new to Subversion 1.5, specifies the path of a MIME types mapping file, such as the
mime.typesfile provided by the Apache HTTP Server. Subversion uses this file to assign MIME types to newly added or imported files. See the section called “Automatic Property Setting” and the section called “File Content Type” for more about Subversion's detection and use of file content types.no-unlockThis Boolean option corresponds to svn commit's
--no-unlockoption, which tells Subversion not to release locks on files you've just committed. If this runtime option is set toyes, Subversion will never release locks automatically, leaving you to run svn unlock explicitly. It defaults tono.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
.mineor.(whereREVREVis 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 fileReleaseNotes.pdfwas conflicted, the conflict files might be namedReleaseNotes.pdf.mineorReleaseNotes.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
pdfis one of the extensions configured in this list thereof, the conflict files generated forReleaseNotes.pdfwould instead be namedReleaseNotes.pdf.mine.pdfandReleaseNotes.pdf.r4231.pdf. Because each file ends in.pdf, the correct default application will be used to view them. 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.
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
...]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. (If you need to use a semicolon in your
property's name or value, you can escape it by doubling
it.)
$ cat ~/.subversion/config … [auto-props] *.c = svn:eol-style=native *.html = svn:eol-style=native;svn:mime-type=text/html;; charset=UTF8 *.sh = svn:eol-style=native;svn:executable … $ cd projects/myproject $ svn status ? www/index.html $ svn add www/index.html A www/index.html $ svn diff www/index.html … Property changes on: www/index.html ___________________________________________________________________ Added: svn:mime-type ## -0,0 +1 ## +text/html; charset=UTF8 Added: svn:eol-style ## -0,0 +1 ## +native $
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.
New to Subversion 1.8, the [working-copy]
section is used for configuring working copies. Valid options in
this section are:
exclusive-locking-clientsEnables exclusive SQLite locking of working copies for the client, hence improving performance for working copies located on network disks. By setting this config variable to
svn, you instruct Subversion command-line client to use exclusive locking. This reduces the locking overhead but does mean that only one Subversion client will be able to access the working copy at a time. A second client attempting to access a locked working copy will block for 10 seconds and then get an error. In most cases shared locking is preferred but if the working copy is on a network disk rather than a local disk the locking overhead is more significant. When dealing with large working copies on network disks exclusive locking may give a significant performance gain, two or three times faster in some cases. This option is new to Subversion 1.8.exclusive-lockingSetting this config variable to
trueenables exclusive SQLite locking of working copies for all Subversion 1.8 clients. Enabling this may cause some clients to fail to work properly. The default value for this option isfalse. This option is new to Subversion 1.8.
The servers file contains
Subversion configuration options related to the network
layers. There are two special sections 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-auth-typesThis is a semicolon-delimited list of HTTP authentication types which the client will deem acceptable. Valid types are
basic,digest, andnegotiate, 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 isdigest;negotiate—omittingbasicfrom the list. (Note that this setting is only honored by Subversion's Neon-based HTTP provider module.)http-compressionThis 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 tonoto disable compression, such as when debugging network transmissions.http-libraryThe
http-libraryruntime configuration option allows users to specify (generally, or in a per-server-group fashion) which of the available WebDAV access modules they'd prefer to use. Prior to version 1.8, Subversion offered a pair of such modules: its original implementiationlibsvn_ra_neon(selected by using the valueneonfor this option) and the newerlibsvn_ra_serf(selected using the valueserf). As of Subversion 1.8, onlylibsvn_ra_serfis supported. This configuration option remains, though, because the runtime configuration area is version-agnostic. Users with multiple versions of Subversion installed may still wish to enable the use oflibsvn_ra_neonfor sites which they access with an older version of Subversion.http-proxy-exceptionsThis 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-hostThis 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-passwordThis specifies the password to supply to the proxy machine. It defaults to an empty value.
http-proxy-portThis specifies the port number on the proxy host to use. It defaults to an empty value.
http-proxy-usernameThis specifies the username to supply to the proxy machine. It defaults to an empty value.
http-timeoutThis 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. In Subversion 1.8 (or older versions employing the Serf-based HTTP provider), use the value
0to disable the timeout altogether.neon-debug-maskThis is an integer mask that the Neon HTTP library uses for choosing what type of debugging output to yield. The default value is
0, which will silence all debugging output. Prior to version 1.8, most Subversion clients used Neon (via thelibsvn_ra_neonrepository access module) for WebDAV/HTTP communications between the Subversion client and server. Support forlibsvn_ra_neonwas dropped in Subversion 1.8, though, making this option obsolete for newer Subversion installations.ssl-authority-filesThis 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-client-cert-fileIf 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-passwordIf 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
serversfile), you can set this variable to the certificate's passphrase. You won't be prompted anymore.ssl-pkcs11-providerThe 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, which was removed in Subversion 1.8.
ssl-trust-default-caSet this variable to
yesif you want Subversion to automatically trust the set of default CAs that ship with OpenSSL.store-auth-credsThis 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.store-passwordsThis 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 tonoto disable this on-disk password caching. You can override this option for a single instance of the svn command using the--no-auth-cachecommand-line parameter (for those subcommands that support it). For more information regarding that, see the section called “Caching credentials”. Note that regardless of how this option is configured, Subversion will not store passwords in plaintext unless thestore-plaintext-passwordsoption is also set toyes.store-plaintext-passwordsThis variable is only important on UNIX-like systems. It controls what the Subversion client does in case the password for the current authentication realm can only be cached on disk in unencrypted form, in the
~/.subversion/auth/caching area. You can set it toyesornoto enable or disable caching of passwords in unencrypted form, respectively. The default setting isask, which causes the Subversion client to ask you each time a new password is about to be added to the~/.subversion/auth/caching area.store-ssl-client-cert-ppThis option controls whether Subversion will cache SSL client certificate passphrases provided by the user. Its value defaults to
yes. Set this tonoto disable this passphrase caching.store-ssl-client-cert-pp-plaintextThis 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
ask, which causes the Subversion client to ask you each time a new client certificate passphrase is about to be added to the~/.subversion/auth/caching area. Set this option's value toyesornoto indicate your preference and avoid related prompts.