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 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.[54] 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 第 1.1 节 “svn 选项”.
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:
命令行选项
用户INI配置文件
用户注册表值
系统INI配置文件
系统注册表值
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 例 7.1 “注册表条目(.reg)文件样例”), and then
double-click on that file's icon in the Explorer shell, which will cause the
data to be merged into your Registry.
例 7.1. 注册表条目(.reg)文件样例
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"="" "#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]
例 7.1 “注册表条目(.reg)文件样例” 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 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-types
This is a semicolon-delimited list of HTTP authentication types which the
client will deem acceptable. Valid types are basic,
digest, and negotiate, 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 digest;negotiate—omitting
basic from the list. (Note that this setting is only
honored by Subversion's Neon-based HTTP provider module.)
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-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-password
指定代理服务器的密码。缺省为空。
http-proxy-port
指定代理服务器的端口。缺省值为空。
http-proxy-username
指定代理服务器的用户名。缺省值为空。
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.
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 第 8 章 嵌入 Subversion.
ssl-authority-files
这是一个分号分割的路径和文件列表，这些文件包含了Subversion客户端在用HTTPS访问时可以接受的认证授权(或者CA)证书。
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.
ssl-pkcs11-provider
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.
ssl-trust-default-ca
如果你希望Subversion可以自动相信OpenSSL携带的缺省的CA，可以设置为yes。
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.
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 regarding that, see
第 11.2.1 节 “缓存凭证”. Note that regardless
of how this option is configured, Subversion will not store passwords in
plaintext unless the store-plaintext-passwords option is
also set to yes.
store-plaintext-passwords
This 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 to
yes or no to enable or disable caching
of passwords in unencrypted form, respectively. The default setting is
ask, 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-pp
This option controls whether Subversion will cache SSL client certificate
passphrases provided by the user. Its value defaults to
yes. Set this to no to disable this
passphrase caching.
store-ssl-client-cert-pp-plaintext
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
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 to yes or no to
indicate your preference and avoid related prompts.
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-stores
This 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,
windows-crypto-api, representing the GNOME Keyring, KDE Wallet,
Mac OS X Keychain, and Microsoft Windows cryptography API, respectively.
Listed stores which are not available on the system are ignored.
store-passwords
This option has been deprecated from the config file.
It now lives as a per-server configuration item in the
servers configuration area. See 第 1.3.1 节 “服务器” for details.
store-auth-creds
This option has been deprecated from the config file.
It now lives as a per-server configuration item in the
servers configuration area. See 第 1.3.1 节 “服务器” for details.
The [helpers] section controls which external
applications Subversion uses to accomplish its tasks. Valid options in this
section are:
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 第 4 节 “使用外置比较与合并工具” 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 第 4 节 “使用外置比较与合并工具” for more details on using such programs.
diff3-has-program-arg
如果diff3-cmd选项设置的程序接受一个--diff-program命令行参数，这个标记必须设置为true。
editor-cmd
This specifies the program Subversion will use to query the user for certain types of textual metadata or when interactively resolving conflicts. See 第 3 节 “使用外置编辑器” for more details on using external text editors with Subversion.
merge-tool-cmd
This specifies the program that Subversion will use to perform three-way merge operations on your versioned files. See 第 4 节 “使用外置比较与合并工具” 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 第 3.4 节 “穿越 SSH 隧道”.
The miscellany section is where everything that doesn't
belong elsewhere winds up.[55] In this
section, you can find:
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.
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 第 4.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 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-ignore command-line flag.
For information on finer-grained control of ignored items, see 第 5 节 “忽略未版本控制的条目”.
interactive-conflicts
This 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 第 4.5 节 “解决冲突”. Otherwise, it will simply flag the
conflict and continue its operation, postponing resolution to a later time.
log-encoding
This variable sets the default character set encoding for commit log
messages. It's a permanent form of the --encoding option
(see 第 1.1 节 “svn 选项”). 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-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 第 3.4 节 “自动设置属性” and 第 4.1 节 “文件内容类型” for more
about Subversion's detection and use of file content types.
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.
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
. (where
REVREV 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.
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. 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.