This documentation was written to describe Subversion 1.5. If you are running a newer version of Subversion, we strongly suggest that you visithttp://www.svnbook.com/ and consult the version of this book appropriate for your version of Subversion.
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 Subversionconfiguration area is a two-tiered hierarchy of option names and their values. Usually, this boils down to a special directory that containsconfiguration files (the first tier), which are just text files in standard INI format (with “sections” providing 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 thesvn 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 namedSubversion, typically inside theApplication 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.[49] 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 thesvn 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 aSubversion directory inside the commonApplication Data location (again, as specified by the Windows Registry). Unlike the per-user case, thesvn program does not attempt to create the system-wide configuration area.
The per-user configuration area currently contains three files—two configuration files (config andservers), and aREADME.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 innocuoussvn command, such assvn --version. A new configuration directory with the default contents will be created.
The per-user configuration area also contains a cache of authentication data. Theauth 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 theHKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion key. For example, theglobal-ignores option, which is in themiscellany section of theconfig file, would be found atHKEY_LOCAL_MACHINE\Software\Tigris.org\Subversion\Config\Miscellany\global-ignores. Per-user configuration values should be stored underHKEY_CURRENT_USER\Software\Tigris.org\Subversion.
Registry-based configuration options are parsedbefore 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.
Thesvn 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 theREGEDIT program. Alternatively, you can create a.reg file (such as the one inExample 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-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-passwords"="yes""#store-auth-creds"="yes"[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\tunnels][HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\miscellany]"#global-ignores"="*.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#* .DS_Store""#log-encoding"="""#use-commit-times"="""#no-unlock"="""#enable-auto-props"=""[HKEY_CURRENT_USER\Software\Tigris.org\Subversion\Config\auto-props]
The previous example 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.
Theservers file contains Subversion configuration options related to the network layers. There are two special section names in this file—groups andglobal. Thegroups section is essentially a cross-reference table. The keys in this section are the names of other sections in the file; their values areglobs—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.comcollabnet = 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 thegroups section. If a match is made, Subversion then looks for a section in theservers file whose name is the matched group's name. From that section, it reads the actual network configuration settings.
Theglobal section contains the settings that are meant for all of the servers not matched by one of the globs under thegroups 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 specialgroups section), and are as follows:
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-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-proxy-passwordThis specifies the password 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. The default value is0, which instructs the underlying HTTP library, Neon, to use its default timeout setting.
http-compressionThis specifies whether Subversion should attempt to compress network requests made to DAV-ready servers. The default value isyes (though compression will occur only if that capability is compiled into the network layer). Set this tono to disable compression, such as when debugging network transmissions.
http-librarySubversion provides a pair of repository access modules that understand its WebDAV network protocol. The original one, which shipped with Subversion 1.0, islibsvn_ra_neon (though back then it was calledlibsvn_ra_dav). Newer Subversion versions also providelibsvn_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 thehttp-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 orserf.
http-auth-typesThis option is a semicolon-delimited list of authentication types supported by the Neon-based WebDAV repository access modules. Valid members of this list arebasic,digest, andnegotiate.
neon-debug-maskThis is an integer mask that the underlying HTTP library, Neon, uses for choosing what type of debugging output to yield. The default value is0, which will silence all debugging output. For more information about how Subversion makes use of Neon, seeChapter 8,Embedding Subversion.
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-trust-default-caSet this variable toyes if you want Subversion to automatically trust the set of default CAs that ship with OpenSSL.
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 theservers file), you can set this variable to the certificate's passphrase. You won't be prompted anymore.
Theconfig 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.
Theauth section contains settings related to Subversion's authentication and authorization against the repository. It contains the following:
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 isyes. Set this tono to disable this on-disk password caching. You can override this option for a single instance of thesvn command using the--no-auth-cache command-line parameter (for those subcommands that support it). For more information, seethe section called “Client Credentials Caching”.
store-auth-credsThis setting is the same asstore-passwords, except that it enables or disables on-disk caching ofall authentication information: usernames, passwords, server certificates, and any other types of cacheable credentials.
Thehelpers section controls which external applications Subversion uses to accomplish its tasks. Valid options in this section are:
editor-cmdThis specifies the program Subversion will use to query the user for certain types of textual metadata or when interactively resolving conflicts. Seethe section called “Using External Editors” for more details on using external text editors with Subversion.
diff-cmdThis specifies the absolute path of a differencing program, used when Subversion generates “diff” output (such as when using thesvn diff command). By default, Subversion uses an internal differencing library—setting this option will cause it to perform this task using an external program. Seethe section called “Using External Differencing and Merge Tools” for more details on using such programs.
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. Seethe section called “Using External Differencing and Merge Tools” for more details on using such programs.
diff3-has-program-argThis flag should be set totrue if the program specified by thediff3-cmd option accepts a--diff-program command-line parameter.
merge-tool-cmdThis specifies the program that Subversion will use to perform three-way merge operations on your versioned files. Seethe section called “Using External Differencing and Merge Tools” for more details on using such programs.
Thetunnels section allows you to define new tunnel schemes for use withsvnserve andsvn:// client connections. For more details, seethe section called “Tunneling over SSH”.
Themiscellany section is where everything that doesn't belong elsewhere winds up.[50] In this section, you can find:
global-ignoresWhen running thesvn status command, Subversion lists unversioned files and directories along with the versioned ones, annotating them with a? character (seethe 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-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 assvn status, thesvn add andsvn 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, seethe section called “Ignoring Unversioned Items”.
enable-auto-propsThis instructs Subversion to automatically set properties on newly added or imported files. The default value isno, so set this toyes to enable this feature. Theauto-props section of this file specifies which properties are to be set on which files.
log-encodingThis variable sets the default character set encoding for commit log messages. It's a permanent form of the--encoding option (seethe section called “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-timesNormally your working copy files have timestamps that reflect the last time they were touched by any process, whether your own editor or somesvn 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. Thesvn export command always places these “last-commit timestamps” on trees that it produces. By setting this config variable toyes, thesvn checkout,svn update,svn switch, andsvn revert commands will also set last-commit timestamps on files that they touch.
mime-types-fileThis option, new to Subversion 1.5, specifies the path of a MIME types mapping file, such as themime.types file provided by the Apache HTTP Server. Subversion uses this file to assign MIME types to newly added or imported files. Seethe section called “Automatic Property Setting” andthe section called “File Content Type” for more about Subversion's detection and use of file content types.
preserved-conflict-file-extsThe 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. (whereREVREV 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 fileReleaseNotes.pdf was conflicted, the conflict files might be namedReleaseNotes.pdf.mine orReleaseNotes.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 thatpdf is one of the extensions configured in this list thereof, the conflict files generated forReleaseNotes.pdf would instead be namedReleaseNotes.pdf.mine.pdf andReleaseNotes.pdf.r4231.pdf. Because each file ends in.pdf, the correct default application will be used to view them.
interactive-conflictsThis is a Boolean option that specifies whether Subversion should try to resolve conflicts interactively. If its value isyes (which is the default value), Subversion will prompt the user for how to handle conflicts in the manner demonstrated inthe section called “Resolve Conflicts (Merging Others' Changes)”. Otherwise, it will simply flag the conflict and continue its operation, postponing resolution to a later time.
no-unlockThis Boolean option corresponds tosvn commit's--no-unlock option, 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 runsvn unlock explicitly. It defaults tono.
Theauto-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 formatPATTERN = PROPNAME=VALUE[;PROPNAME=VALUE ...], wherePATTERN 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 theconfig file. Lastly, don't forget to setenable-auto-props toyes in themiscellany section if you want to enable auto-props.
You are readingVersion Control with Subversion (for Subversion 1.5), by Ben Collins-Sussman, Brian W. Fitpatrick, and C. Michael Pilato.
This work is licensed under theCreative Commons Attribution License v2.0.
To submit comments, corrections, or other contributions to the text, please visithttp://www.svnbook.com/.