7.1 Runtime Configuration Area

The user can control many optional behaviors that Subversion provides. Users can apply these options to all Subversion operations. So, rather than forcing users to remember command-line arguments for specifying these options, and to use them for each and every operation they perform, Subversion uses configuration files, segregated into a Subversion configuration area.

The Subversion 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 (with sections providing the second tier). These files can be easily edited using your favorite text editor (such as Emacs or vi), and contain directives read by the client to determine which of several optional behaviors the user prefers.

7.1.1 Configuration Area Layout

The first time that 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.^[1] We will refer to the per-user configuration area using its Unix name, .subversion.

^[1] The APPDATA environment variable points to the Application Data area, so you can always refer to this folder as %APPDATA%\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 does not alone 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 again 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 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 modify the desired option's value. If 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.

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.

7.1.2 Configuration and the Windows Registry

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 are overridden by values found in the configuration files. In other words, configuration priority is granted in the following order on a Windows system:

1. Command-line options

2. The per-user INI files

3. The per-user Registry values

4. The system-wide INI files

5. 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, and then double-click on that file from the Explorer shell, which merges the data into your registry (see Example 7-1).

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-proxy-host"="" "#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"="" [HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\auth] "#store-auth-creds"="no" [HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\helpers] "#editor-cmd"="notepad" "#diff-cmd"="" "#diff3-cmd"="" "#diff3-has-program-arg"="" [HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\miscellany] "#global-ignores"="*.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#*" "#log-encoding"="" "#use-commit-times"="" "#template-root"="" "#enable-auto-props"="" [HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\tunnels] [HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\auto-props]

The previous example shows the contents of a .reg file that 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.

7.1.3 Configuration Options

In this section, we discuss the specific runtime configuration options that are currently supported by Subversion.

7.1.3.1 Servers

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 which 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 valid for the other server sections in the file (except, of course, the special groups section), and are as follows:

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 does not attempt to route HTTP requests through a proxy computer, and instead attempts 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 timeout, 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 or not Subversion should attempt to compress network requests made to DAV-ready servers. The default value is yes (though compression will only occur if that capability is compiled into the network layer). Set this to no to disable compression, such as when debugging network transmissions.

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 silences all debugging output. For more information about how Subversion makes use of Neon, see Chapter 8.

ssl-authority-files

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 trust the set of default CAs that ship with OpenSSL automatically.

ssl-client-cert-file

If host (or set of hosts) requries an SSL client certificate, you normally are prompted for a path to your certificate. By setting this variable to that same path, Subversion can find your client certificate automatically without prompting you. There's no standard place to store your certificate on disk; Subversion grabs 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), then you can set this variable to the certificate's passphrase. You won't be prompted anymore.

7.1.3.2 Config

The config file contains the rest of the currently available Subversion run-time options, those not related to networking. There are only a few options in use at this time, 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:

store-auth-creds

This instructs Subversion to cache, or not to cache, authentication credentials 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 credential 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 Section 6.2.2.

The helpers section controls which external applications Subversion uses to accomplish its tasks. Valid options in this section are as follows:

editor-cmd

This specifies the program Subversion will use to query the user for a log message during a commit operation, such as when using svn commit without either the --message (-m) or --file (-F) options. This program is also used with the svn propedit command a temporary file is populated with the current value of the property the user wishes to edit, and the edits take place right in the editor program (see Section 7.2). This option's default value is empty. If the option is not set, Subversion will fall back to checking the environment variables SVN_EDITOR, VISUAL, and EDITOR (in that order) for an editor command.

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 causes it to perform this task using an external program.

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.

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.

The tunnels section allows you to define new tunnel schemes for use with svnserve and svn:// client connections. For more details, see Section 6.3.3.

The miscellany section is where everything that doesn't belong elsewhere winds up.^[2] In this section, you can find:

^[2] Anyone for potluck dinner?

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 Section 3.5.3.1). 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 which 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 .*~ *~ .#*.

You can override this option for a single instance of the svn status command by using the --no-ignore command-line flag. For information on more fine-grained control of ignored items, see Section 7.2.3.3 later in this chapter.

enable-auto-props

This instructs Subversion to set properties automatically on newly added or imported files. The default value is no, so set this to yes to enable auto-props.

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=PROPVALUE where PATTERN is a regular expression that matches a set of filenames and the rest of the line is the property and its value. 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 if you want to enable auto-props.

log-encoding

This variable sets the default character set encoding for commit log messages. It's a permanent form of the --encoding option (see Section 9.1.1). The Subversion repository stores log messages in UTF8, 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, i.e., by your own editor or by 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 also sets last-commit timestamps on files that they touch.