Section 7.2. Editing the Configuration Files

7.2. Editing the Configuration Files

Inside the configuration directory (e.g., .subversion), you will find two configuration files that you can edit: config and servers. These are both plain text files with options that you can change. (Subversion sets them up with reasonable defaults when they are created.) You will also find a file named README.txt, which explains the format of the configuration files. In many cases, there will also be a directory named auth, which contains repository authentication information. Unless you really know what you're doing, there is very little in the auth directory that can be edited by hand.

7.2.1. The config File

The configuration file config is used to set a variety of options that control how a Subversion client will act by default. The file itself is broken down into four sections, each of which contains several different options. The sections (in the order they appear in the automatically generated default config file) are: [auth], [helpers], [tunnels], and [miscellany].^[1]

^[1] This is accurate through version 1.1 of Subversion. Subsequent versions may introduce new options or sections.

Setting the Authorization Retention

The first configuration section, [auth], has two options (one of which was added in version 1.1). The first controls whether Subversion saves your passwords to repositories (in the .subversin/auth directory), whereas the second allows you to turn off all caching of authentication credentials to disk. By default, Subversion does save your authorization information, but for security purposes that may not be what you want. This is especially useful if a working copy is shared by multiple people who have their own repository accounts, but share a shell account on the machine where the working copy resides (on a test server, for instance). In such a case, it would be much better if Subversion demanded a username and password every time the repository was accessed, which is what you will get if you set Subversion to not store passwords.

The option to set for turning off password caching is called store-password, and should be set to either yes or no, as in this example, which shows a complete [auth] section:

 [auth] store-password = yes 

If you want to go a step further and disable all authentication caching, you can instead set the store-auth-creds to no. If you use store-auth-creds, there is no need to also use store-passwords, because password storing is disabled by this option, along with the caching of any other credentials, including usernames and SSL or SSH certificates.

 [auth] store-auth-creds = no 

Setting Your Helper Programs

Subversion has the capability to make use of several external utility programs (although it has its own internal default version for most of them). If you need to change which programs Subversion uses, you can set those in the [helpers] section of the config file.

One of the helpers that you may want to modify is the text editor that Subversion uses to obtain log entries from users when they run commands that modify the repository. By default, Subversion looks at the environment variables $SVN_EDITOR, $VISUAL, and then $EDITOR to determine which program to run. If you would rather specify that command in the configuration file, though, you can override Subversion's environment variable checking by setting the editor-cmd option, like in the following example entry.

 editor-cmd = /usr/bin/emacs 

The other set of programs that you may need to set are the diff programs that Subversion uses to compare files. Subversion has its own diffing algorithms built into the system, but you may find that a third-party diff tool, such as GNU diff, better serves your needs. For instance, if you need the output of a Subversion diff command to be in a format other than the unified diff format that Subversion uses, you would need to use an external diff tool.

Subversion uses two different diff commands, each of which you can independently set a command for. The first is the standard diff program, used for finding the differences between two files, and is set by the diff-cmd option. The other diff program that Subversion uses is a three-way diff, which it uses when performing merges. You can set the three-way diff program with diff3-cmd. You can also tell Subversion whether it should pass a --diff-program option to the three-way diff command to tell it which two-way diff program to use, using the diff3-has-program-arg option. If you do change the default diff command, there is one word of caution: Subversion assumes that your command takes GNU-style diff/diff3 options, so you may have to write a wrapper script to do a conversion.

The following example shows how you might set up the diff commands in the config file.

 diff-cmd = /usr/bin/diff diff3-cmd = /usr/bin/diff3 diff3-has-program-arg = false 

Setting Up Tunnels

Subversion has the capability to access a remote repository by tunneling through another program to a remote server. When it connects to the remote server, it will run svnserve on the remote server to connect to the repository. Normally, the scheme used for tunneling is SSH (which Subversion supports by default), but you can set up other tunneling schemes through your config file.

Entries for different tunneling schemes are entered in the [tunnels] section of the config file. Each entry defines a different scheme (and the program that Subversion should use for the tunneling). The basic form for the entries is the name of the scheme, followed by an equals sign, and then the name of the program that Subversion should run (along with any options that should be fed to the program). So, to set up Subversion to be able to tunnel through rsh, using the username bill, you could set up your config file with an entry like the following example.

 rsh = /usr/bin/rsh -l bill 

To invoke this scheme, you would then run your Subversion client with a repository URL such as svn+rsh://svn.example.com/var/svn/myrepos, which would cause Subversion to run the command

 rsh -l bill svn.example.com svnserve -t 

You can add as many tunneling schemes as you want, and can use whatever names you would like to identify them. This means that you could set up multiple schemes in the config file to use the same program with different options, such as these entries, which set up two SSH schemes for connecting with different usernames.

 ssh_bill = ssh -l bill ssh_drew = ssh -l drew 

Setting Global Ignores

Often, you will end up with files in your working copy that you have no intention of ever adding to the repository. For example, object files that are generated when you compile a program are not something that you usually want to store in the repository, instead preferring to have them regenerated in each individual working copy. The problem with files you don't want to ever add to the repository is that they can easily clutter the output of the Subversion status command, and can often get accidentally committed if you are not careful.

The solution is to use global ignores in your config file, to give Subversion file patterns that it should ignore when running Subversion commands. So, if you don't want to see object files, you could tell Subversion to ignore all files that end in .o. Ignore patterns are entered under the [miscellany] section, with the option global-ignores. As an example, the following entry would tell Subversion to ignore all files that end in .o or .exe.

 global-ignores = *.o *.exe 

Setting the Log File Encoding

Subversion always stores log messages in UTF8, using your local system's locale. In some cases, though, your editor may be providing log messages to Subversion in a different encoding. If that is the case, you need to tell Subversion what encoding to expect so that it can perform the proper conversions. To do that, you can set the log-encoding option under the [miscellany] section, like in this entry, which tells Subversion to use ASCII encoding.

 log-encoding = ascii 

Controlling File Timestamps

When you check out or update a file in a working copy, the timestamps on files will normally reflect the date and time when the checkout or update created the current version of the file in your working copy. If you would instead like to have the timestamps reflect the last time those files were changed in the repository, you can tell Subversion to set them appropriately by setting the use-commit-times option (in the [miscellany] section) to yes, so that your entry will look like this:

 use-commit-times = yes 

Automatically Setting Properties

Subversion has the capability to automatically assign property values to files, based on their names, using rules that are set up in the config file. To turn auto properties on, you need to set the enable-auto-props option to yes in the [miscellany] section (or enable it on the command line with --auto-props when a command is run). Then, you can add an [auto-props] section to your config file and set up as many automatic property entries as you need. Each entry consists of a filename pattern (which can use wildcards to match multiple files), followed by an equals sign, followed by a semicolon-separated list of property/value pairs. For example, the following snippet shows a sample [auto-props] section.

 [auto-props] *.c = svn:keywords=Id *.h = svn:keywords=Id *.bat = svn:eol-style=CRLF;svn:executable 

7.2.2. The servers File

In most cases, connecting to Subversion repositories will require no special intervention. You will just give the URL to your Subversion client and everything will work. Occasionally, though, some repositories will require extra information to connect properly. For instance, you may need to set up parameters for using an HTTP proxy to deal with a firewall, or fine-tune the way the Subversion client handles SSL certificates for a secure connection.

Subversion allows you to set these special server-specific connection options in the servers configuration file, which is located in the same place as the config file from the previous section. In it, you can set up a variety of options for connecting to specific servers, or groups of servers.

Setting Up Server Groups

The servers file is split into three types of sections.

• One or more sections that define the server options for individual groups

• A section that defines the groups (and the servers they are associated with)

• A section that defines global server options

You define groups in the [groups] section. Each entry defines a group, along with the server or servers that the group applies to. Servers can either be entered as a single server name (such as svn.example.com) or with wildcards to match an entire domain (such as *.example.com). You can also add more than one specific server or server pattern by entering multiple servers, separated by commas. As an example, the following sample [groups] section sets up two groups of servers.

 [groups] mygroup = svn.example.com myothergroup = svn.example.org,*.example.net 

You can have as many groups as you would like, and can give each group a name that makes sense to you. The names that you use will then be used later in the document as the section headings to identify which group a set of options applies to.

Configuring HTTP Proxies

HTTP proxies are used for a wide-ranging variety of reasons, from security to traffic management to preventing access to certain sites or domains (and a lot of things in between). Proxies act as an intermediary for HTTP requests. They receive requests from clients, and then forward the request to the real server. Therefore, a client needs to be configured to send requests to the proxy, instead of trying to contact the server directly. In Subversion, the place to configure proxies is in the servers configuration file. For each group, you can specify all of the information necessary to direct your requests through a proxy, as well as specify certain servers that won't need the proxy. The following example shows how you might set up a group of servers to use a proxy.

 [mygroup] http-proxy-host = proxy.example.com http-proxy-port = 8880 http-proxy-username = bill http-proxy-password = mypasswd http-proxy-exceptions = internal-1.example.com *.internal-example.com 

This sets up Subversion to send all requests to the server in mygroup tHRough the proxy.example.com proxy server, which is listening on port 8880. When it connects to the proxy, it will use the username and password that you have supplied. If you don't supply a username or password, Subversion will have to ask you for them on every request, which can get very annoying (imagine typing your username and password 50 to 60 times per day). Because the password is stored in plain text, though, you need to be careful and make sure that the servers file is not readable by anyone but yourself. Finally, the http-proxy-exceptions option allows you to specify certain servers or domains that Subversion should contact directly, instead of through the proxy.

Configuring Other HTTP Stuff

Subversion has a couple of other HTTP-related options that are unrelated to proxies, but are worth mentioning. They are http-timeout and http-compression. In most cases, you will not have to change either option. However, if you have an especially slow-to-respond repository server, you may need to set http-timeout to a high number to avoid premature connection failures due to timeouts. Additionally, if you are experiencing unknown failures, you may find it useful to set http-compression to no in order to allow you to look at the network packets that are being sent, in the hopes of debugging the problem. By default, Subversion does use HTTP compression, if the server supports it.

Dealing with SSL Certificates

Often, the data that is in a repository is not something that you want everyone to get their hands onor if it is something you want everyone to get their hands on, the odds are that you don't want everyone to be able to directly modify the repository. For this reason, many repositories are accessible only through a secure HTTP link, which is encrypted using the Secure Socket Layer (SSL). If a repository that you are connecting to is set up thus, it may be necessary for you to configure Subversion to recognize the certificate that identifies the server and the keys for connecting to it.

The first thing that you may need to do is to tell Subversion which certificate authorities it should use to validate a server certificate. A certificate authority (CA) is a trusted source, which is capable of validating the authenticity of a certificate you receive. Without the certificate authority, you have no way to ensure that a certificate received from a server is valid and authentic. To tell Subversion which certificate authority it should use, you need to get a certificate identifying the CA and then point Subversion to the file containing it. You do so through the ssl-authority-files option in your servers file, which is a list of authority files, separated by colons. If you set the ssl-trust-default-ca option to yes, Subversion will also look to a set of built-in default CAs.

Some servers will require you to have a client certificate to prove your own identity. In this case, you will want to tell Subversion where to find that file, too. Subversion looks for the client certificate in the location pointed to by the ssl-client-cert-file option (if there is no such option listed, it will ask you for the certificate when you run the client). Additionally, you may need to tell Subversion which type of certificate you are providing it, using the ssl-client-cert-type option, which takes pem or pkcs12 as valid values. If your client key isn't stored in the same file as your client certificate, you may also need to tell Subversion where to find it, using the ssl-client-key-file option. If your certificate requires a passphrase, you may also want to place that in your servers file, using the option ssl-client-cert-password option. Be careful though. As with the HTTP-proxy password, this will be stored in plain text, so you need to take steps to secure the servers file itself.

Security is always a good idea, and in general it's a bad idea to turn off the built-in security safeguards that Subversion provides when authenticating a certificateespecially because Subversion can be directed to allow unknown certificates on a case-by-case basis, after prompting for your approval. That said, we're all adults here, and sometimes, even with the best intentions of having a secure environment, the practical reality of things means that you need to cut some security to improve usability. To that end, Subversion provides you with a few options that you can use to relax your communications to an SSLenabled server. If a server has a certificate that is self-signed (or otherwise signed with a certificate authority you can't check), you can direct Subversion to ignore the unknown certificate authority by setting the ssl-ignore-unknown-ca option to yes. Similarly, if you are accessing a machine that has an incorrectly dated certificate, you can set the ssl-ignore-invalid-date option to yes in order to direct Subversion to accept the certificate anyway. And finally, if the host that a server is reporting as its location doesn't match the certificate for that server, you can direct Subversion to allow the mismatch using ssl-ignore-host-mismatch (again, set to yes).

To help tie all of this together, here is a sample servers file, showing a setup that you might use for setting up some sane global SSL options, along with a group that overrides those settings for a couple of local area network servers that have certificates that are not kept properly up-to-date.

 [groups] UnkemptServers = moe.localnet curly.localnet [UnkemptServers] ssl-ignore-unknown-ca = yes ssl-ignore-invalid-date = yes [global] ssl-trust-default-ca = yes ssl-authority-files = /home/bill/.ssl/localCA.pem ssl-client-cert-file = /home/bill/.ssl/myCert.pem ssl-client-cert-password = mI^paSs-42  # this is the password,                                        # not an encrypted version