This Confluence has been LDAP enabled, if you are an ASF Committer, please use your LDAP Credentials to login. Any problems file an INFRA jira ticket please.

Page tree
Skip to end of metadata
Go to start of metadata
Subversion uses configuration files for client, server and repository configuration. Their syntax is based on Windows INI files and is a subset of the syntax supported by Python's configparser module.

Syntax Description

Configuration files are plain text files that consist of a number of sections, each containing zero or more options:

# Comment ...

[section.1]
 
[section.2]
name.1 = value
name.2: multi-line
        value

Ignored Matter

Empty lines and lines that start with a ‘#’ in the first column are ignored (except in multi-line-values, see below).

Sections

A section starts with a section header. The section header must be the first line in the configuration file, except for empty lines or comments.

The section header starts with a left bracket ‘[’ in the first column. Everything between the opening bracket and the first right bracket ‘]’ in the line is the section name. Any text between that right bracket and the end of the line is ignored. The following are valid section headers:

[section]
[  section name with spaces  ]
[another.section]  With some ignored text after the name

(warning) For future compatibility, we strongly recommend not writing anything after the closing bracket of the section name. If you want to document a section, write a comment before or after the section header. We also recommend not using spaces in section names, because all spaces are significant, including spaces immediately after the opening bracket and before the closing bracket.

Recommended:

    # Documentation for section.1
[section.1]

[section.2]
# Documentation for section.2

Not recommended:

    [section] Documentation
[ name with confusing leading and trailing spaces; can you count them? ]


Section names are case-insensitive and case-preserving. This means that, for example, you cannot have two different sections named [Section] and [section]; these are both treated as the same section. This becomes important when a section is reopened (see below).

(warning) For compatibility with external tooling, we recommend not relying on case-insensitive section names. For example, Python's configparser treats section names as case-sensitive by default.

The [DEFAULT] Section

The [DEFAULT] section is special: it can be used to define default values for options and is also used for value expansion (see below).

Default values are used when an option is expected to be in a given section but is not defined there. In that case, any option with the same name defined in the [DEFAULT] section is used instead. For example, given the following configuration file:

[DEFAULT]
i = √(2, −1)
e = √(%(i)s × %(π)s, −1)
[rational-approximation]
π = 3.1415926535897932384626433832795028841971693993751
["educational"]
π = 3

the value of “e” in section [rational-approximation] will be a quite satisfactory “2.7182818284590…”, but the value from the ["educational"] section will be a sad “2.849653908” which one might as well round up to the definition of “π” in that section. (That's all assuming that the config parser implemented the function “√(base, argument)”.)

Reopening Sections

A section is implicitly closed when another section header is encountered. However, the section may be reopened by repeating its section header, and new options can be defined or existing options can be redefined. In the following example, [section] ends up containing a single option called “name” whose value is “updated value”.

[section]
name = value
[another.section]
[Section]
name = updated value

(warning) For compatibility with external tooling, we recommend you do not reopen sections. For example, the ConfigParser module in Python 2 allows that, but configparser in Python 3 does not (by default).

Options

An option is a mapping between a name and a value. Options cannot appear outside of a section. Options in different sections are considered separate even if they have the same name.

There are two valid ways to define an option:

name = value
name: value

The option name must start in the first column of the line and stops at the separator (‘=’ or ‘:’). This means that:

  • the name cannot start with ‘[’ or  ‘#’, those characters start a section header or a comment;
  • the name may not contain the separators ‘=’ or ‘:’.

Spaces around the separator are optional and are ignored.

Option names, like section names, are case-insensitive and case preserving; and like section names, option names may contain spaces. (warning) But the warnings against relying on case-insensitivity and the use of spaces apply to option names as well.

The options's value is all the text from the separator character until the end of the line. Leading and trailing spaces around the option value are removed, but spaces within the value are preserved.

Multi-Line Values

An option's value may be broken into several lines. Continuation lines must start with at least one space. Trailing spaces in the previous line, the newline character and the leading spaces in the continuation line are removed and replaced with a single space. In the example at the top of this page, the value of the option “name.2” is “multi-line value”, note the single space where the value was continued in the next line.

Comments and empty lines may not appear in multi-line values.

Value Types

At the syntactic level, option values are strings of characters. But certain settings in the configuration files treat them as either logical (Boolean) values or lists.

Boolean Values

Any of the following strings are recognised as truth values (case does not matter):

“True” value“False” value
truefalse
yesno
onoff
10

Lists

When a value is a list, the list elements are separated by commas ‘,’. Spaces around each element are trimmed and successive commas are merged. That means you can't have a list element that is an empty string. The list in the following example contains three elements, “one”, “two” and “three”.

[section]
list = one, two , ,,
       three

Obviously, list elements cannot contain commas.

Note: Some options with list-like values use a different separator (q.v.[auto-props]). Always refer to the specific documentation before you modify any settings.

Value Expansion

Option values may be expanded within another value by enclosing the option's name in parentheses, preceded by a percent sign ‘%’ and followed by an ‘s’:

name.2 = %(name.1)s

The value of the option “name.2” is expanded to the value of “name.1”. Value expansion follows these rules:

  • Expansion is performed recursively: e.g., “name.3” may refer to “name.2” which refers to “name.1”, and all the references will be followed.
  • The referenced option name is first searched for in the same section, and if it is not found there, then in the special [DEFAULT] section. There is no way to refer to options that are defined in a different section.

  • If the referenced option name is not found, the whole “%(name)s” placeholder is left unchanged in the value.

Formal Definition

The following is a formal definition of the configuration file syntax, in BNF:

Subversion Configuration File Syntax
<config-file>   ::= <records> | <ignored> <records> | <end-of-file>
<ignored>       ::= <empty> | <comment> | <ignored> ( <empty> | <comment> )
<records>       ::= <section> | <records> <record>
<record>        ::= <empty> | <comment> | <section> | <entry>
<empty>         ::= <opt-space> <line-end>
<comment>       ::= "#" <opt-text> <line-end>
<section>       ::= "[" <name> "]" <opt-text> <line-end>
<entry>         ::= <option> | <option> <continued>
<option>        ::= <key> <opt-space> <key-sep> <opt-text> <line-end>
<continued>     ::= <continuation> | <continued> <continuation>
<continuation>  ::= <space> <text> <line-end>

<line-end>      ::= <LF> | <end-of-file>
<space>         ::= <space-char> | <space> <space-char>
<name>          ::= <name-char> | <name> <name-char>
<text>          ::= <non-space> | <text> <text-char>
<key>           ::= <key-start> | <key-start> <key-cont> <key-end>
<key-cont>      ::= <key-char> | <key-cont> <key-char> | ""
<opt-space>     ::= <space> | ""
<opt-text>      ::= <opt-space> <text> | ""
<end-of-file>   ::= (the end of the file)

; Character classes
<space-char>    ::= <BS> | <TAB> | <VT> | <FF> | <CR> | <SPC>
<text-char>     ::= (any character except <LF>)
<name-char>     ::= (any <text-char> except "]")
<non-space>     ::= (any <text-char> except <space-char>)
<key-sep>       ::= "=" | ":"
<key-start>     ::= (any <non-space> except <key-sep>, "#" and "[")
<key-end>       ::= (any <non-space> except <key-sep>)
<key-char>      ::= (any <text-char> except <key-sep>)

; Characters (ASCII and Unicode names)
<BS>            ::= U+0008  BACKSPACE
<TAB>           ::= U+0009  CHARACTER TABULATION
<LF>            ::= U+000A  LINE FEED
<VT>            ::= U+000B  LINE TABULATION
<FF>            ::= U+000C  FORM FEED
<CR>            ::= U+000D  CARRIAGE RETURN
<SPC>           ::= U+0020  SPACE



References

  • No labels