Table of Contents
If you've been reading this book chapter by chapter, from start to finish, you should by now have acquired enough knowledge to use the Subversion client to perform the most common version control operations. You understand how to checkout a working copy from a Subversion repository. You are comfortable with submitting and receiving changes using the svn commit and svn update functions. You've probably even developed a reflex which causes you to run the svn status command almost unconsciously. For all intents and purposes, you are ready to use Subversion in a typical environment.
But the Subversion feature set doesn't stop at “common version control operations”.
This chapter highlights some of Subversion's features that aren't quite so regularly used. In it, we will discuss Subversion's property (or “metadata”) support, and how to modify Subversion's default behaviors by tweaking its run-time configuration area. We will describe how you can use externals definitions to instruct Subversion to pull data from multiple repositories. We'll cover in detail some of the additional client- and server-side tools that are part of the Subversion distribution.
Before reading this chapter, you should be familiar with the basic file and directory versioning capabilities of Subversion. If you haven't already read about those, or if you need a refresher, we recommend that you check out Chapter 2, Basic Concepts and Chapter 3, Guided Tour. Once you've mastered the basics and consumed this chapter, you'll be a Subversion power-user!
Subversion provides many optional behaviors that can be controlled by the user. 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 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.
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.
[29]
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 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 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 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.
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 are overridden by values found in the configuration files. In other words, configuration priority is granted in the following order on a Windows system:
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, and then double-click on that
file from 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-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 .*~ *~ .#* .DS_Store" "#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 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 run-time configuration options that are currently supported by Subversion.
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-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 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-compressionThis 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-maskThis 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, Developer Information.
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 to yes 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 the servers file),
then 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 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-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 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 the section called “Client Credentials Caching”.
store-auth-credsThis setting is the same as
store-passwords, except that it
enables or disables 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-cmdThis 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 the section called “Properties”). This option's default
value is empty. The order of priority for determining the
editor command is:
Command-line option --editor-cmd
Environment variable SVN_EDITOR
Configuration option editor-cmd
Environment variable VISUAL
Environment variable EDITOR
Possibly, a default value built in to Subversion (not present in the official builds)
The value of any of these options or variables is
(unlike diff-cmd) the beginning of a
command line to be executed by the shell. Subversion
appends a space and the pathname of the temporary file to be
edited. The editor should modify the temporary file and
return a zero exit code to indicate success.
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 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. See the section called “Using External Differencing Tools” for more details on using such programs.
diff3-has-program-argThis 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 the section called “SSH authentication and authorization”.
The miscellany section is where
everything that doesn't belong elsewhere winds up.
[30]
In this section, you can find:
global-ignoresWhen 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 “svn status”). 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 .*~ *~
.#* .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
behaviour for a single instance of any of these commands
by explicitly specifying the file name, or by using
the --no-ignore command-line flag.
For information on more fine-grained control of
ignored items, see the section called “svn:ignore”.
enable-auto-propsThis instructs Subversion to automatically set
properties on newly added or imported files. The
default value is no, so set this to
yes to enable Auto-props.
The auto-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 (see
the section called “svn Switches”). 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 that be 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 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=PROPVALUE
where PATTERN is a file pattern
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 in the miscellany
section if you want to enable auto-props.