vcsync.conf − configuration file for vcsync


The file consists of statements terminated with a semicolon. White-space characters (space, horizontal and vertical tabulation, newline, form-feed) are ignored, except as they serve to separate the tokens. Empty lines and comments are ignored. There are two kinds of comments: single-line and multi-line. Single-line comments start with # or // and continue to the end of the line:

# This is a comment
// This too is a comment

Multi-line or C-style comments start with the two characters /* (slash, star) and continue until the first occurrence of */ (star, slash).

Multi-line comments cannot be nested. However, single-line comments may well appear within multi-line ones.

Pragmatic comments are similar to the usual single-line comments, except that they cause some changes in the way the configuration is parsed. Pragmatic comments begin with a # sign and end with the next physical newline character.
#include <

Include the contents of the file file. Both forms are equivalent. The FILE must be an absolute file name.

#include_once <FILE>

Same as #include, except that, if the FILE has already been included, it will not be included again.

#line num
num "FILE"

This line causes the parser to believe, for purposes of error diagnostics, that the line number of the next source line is given by num and the current input file is named by FILE. If the latter is absent, the remembered file name does not change.

# num "FILE"

This is a special form of the #line statement, understood for compatibility with the C preprocessor.

A statement consists of a keyword and the value, separated with any amount of whitespace. Statements are terminated with a semicolon. A value can be one of the following:


A number is a sequence of decimal digits.


A boolean value is one of the following: yes, true, t or 1, meaning true, and no, false, nil, 0 meaning false.

unquoted string

An unquoted string may contain letters, digits, and any of the following characters: _, , ., /, @, *, :.

quoted string

A quoted string is any sequence of characters enclosed in double-quotes ("). A backslash appearing within a quoted string introduces an escape sequence, which is replaced with a single character according to the following rules:

Sequence Expansion ASCII








audible bell









new line



carriage return



horizontal tabulation



vertical tabulation


In addition, the sequence \newline is removed from the string. This allows to split long strings over several physical lines, e.g.:

"a long string may be\
split over several lines"

If the character following a backslash is not one of those specified above, the backslash is ignored and a warning is issued.

Two or more adjacent quoted strings are concatenated, which gives another way to split long strings over several lines to improve readability. The following fragment produces the same result as the example above:

"a long string may be"
" split over several lines"


A here-document is a special construct that allows to introduce strings of text containing embedded newlines.

The <<word construct instructs the parser to read all the following lines up to the line containing only word, with possible trailing blanks. Any lines thus read are concatenated together into a single string. For example:

A multiline

The body of a here-document is interpreted the same way as a double−quoted string, unless word is preceded by a backslash (e.g. <<\EOT) or enclosed in double−quotes, in which case the text is read as is, without interpretation of escape sequences.

If word is prefixed with (a dash), then all leading tab characters are stripped from input lines and the line containing word. Furthermore, is followed by a single space, all leading whitespace is stripped from them. This allows to indent here-documents in a natural fashion. For example:

<<− TEXT
The leading whitespace will be
ignored when reading these lines.

It is important that the terminating delimiter be the only token on its line. The only exception to this rule is allowed if a here-document appears as the last element of a statement. In this case a semicolon can be placed on the same line with its terminating delimiter, as in:

message <<−EOT
Synchronizing project directory.
Please wait.

Block statements
These are special statements that have as their value a list of another statements enclosed in curly braces. The terminating semicolon is optional.


Synchronization settings

Sets the debug level. See the description of meaningful levels in vcsync(8).

vcs−type cvs|svn|git;

Sets the type of VCS to use. The default is cvs.

vcs−command string;

Use string instead of the default VCS command. The default commands are: /usr/bin/cvs, /usr/bin/svn, /usr/bin/git.

destination-root string;

Sets the location of the destination root directory.

timeout number;

Sets command execution timeout in seconds. If the VCS command takes longer than number seconds to execute, it will be forcibly terminated. The default timeout is 5 seconds.

detach boolean;

Detach from the controlling terminal before synchronizing. The detach true statement should be used with cvs, together with the sleep statement (see below).

sleep number;

Wait number of seconds before synchronizing. This is necessary for cvs, to avoid dead-locking.

message string

Output this message to stdout before synchronizing. Notice that it depends on the VCS in use whether this text will be visible to the remote user or not. It works with CVS and GIT, but does not with SVN.

Named configuration
The settings described above set up a global configuration. The configuration file can also contain any number of named configurations, which have the following syntax:

config name {


where statements is a list of statements discussed above. These settings are ignored, unless vcsync is invoked with the −N (−−name) command line option. In that case, the option gives the name of the config block to use instead of the default settings. For example:

vcs-type cvs;
destination-root /var/cvsroot;
detach yes;
sleep 1;

config alt {
    vcs-type svn;
    destination-root /var/svnroot;

Then, to use the svn configuration, vcsync should be run as follows:

vcsync --name alt [other arguments]

Access file

Create files name, instead of the default .htaccess.

access−file−text text;

Add text to the beginning of each created access file.

Checkoutrc keywords
The syntax of .checkoutrc files can be expanded with new keywords, if the need be. There are two kinds of keywords: verbatim and boolean. Verbatim keywords cause the entire line from .checkoutrc to be reproduced in .htaccess. Boolean ones take a boolean value as their argument. If that value evaluates to true, a text assigned to the keyword is inserted in the current position of .htaccess. Otherwise, the keyword is ignored.

You can use the define statement to define new .checkoutrc keywords. Please do so sparingly and consider possible security implications.

Define a verbatim keyword.

define keyword text;

Define a boolean keyword.

The following configuration statement controls the syslog output:

syslog {

facility string;


The statements are:

Set syslog facility. Valid argument values are: user, daemon, auth or authpriv, mail, cron, local0 through local7 (case-insensitive), or a decimal facility number.

tag string;

Tag syslog messages with string. Normally the messages are tagged with the program name.

print−priority bool;

Prefix each message with its priority.

An example syslog statement:

syslog {
    facility local0;
    print-priority yes;




Sergey Poznyakoff <>


Report bugs to <>.


Copyright © 2014 Sergey Poznyakoff
License GPLv3+: GNU GPL version 3 or later <>
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

Manpage server at

Powered by mansrv 1.0