VCSYNC

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
CONFIGURATION
VCS DETECTION
CHECKOUTRC
EXIT CODE
DOWNLOADS
SEE ALSO
AUTHORS
BUG REPORTS
COPYRIGHT

---

NAME

vcsync - synchronize version control system updates with the file system

SYNOPSIS

vcsync [-bdent] [-D DIR] [-N STRING] [-c FILE] [-l PRIO] [-s SECONDS] [-T TYPE] [-w DIR] [--detach] [--config=FILE] [--debug] [--destination-root=DIR] [--checkoutrc=DIR] [--dry-run] [--lint] [--name=STRING] [--sleep=SECONDS] [--stderr] [--vcs-type=TYPE] [ARG...]

vcsync [-HhV] [--usage] [--version] [--help] [--config-help]

DESCRIPTION

It is often necessary to maintain a directory tree which contains files corresponding exactly to the latest version of some version control system repository. Vcsync aims to help solve this problem for CVS, SVN, and GIT.

The synopsis is as follows. There is a version control system repository, whose pathname is REPO_ROOT/PROJECT and a directory DEST_ROOT/PROJECT, called destination directory. The task is to ensure that each check in to the repository be immediately reflected in the destination directory.

To solve that task, vcsync is installed as a hook that is invoked upon each modification of the repository. It takes the information about the VCS in use, repository and destination paths either from the command line options or from its configuration file. The details differ depending on the flavor of VCS used and are described below.

CVS
When used with CVS, the program is invoked from CVSROOT/loginfo as follows:

ALL /usr/bin/vcsync --vcs-type=cvs --detach --sleep=2 -- %p %s

The --vcs-type option tells vcsync which VCS to use. The --detach and --sleep options instruct it to detach from the controlling terminal right after start up and wait for two seconds before performing its job. These two options avoid dead-locking condition which occurs when cvs update is invoked from the loginfo file.

The two dashes mark end of options. This is a precaution for cases when expansion of %p begins with a dash.

If using old CVS format strings, the following line should be used:

ALL /usr/bin/vcsync --vcs-type=cvs --detach --sleep=2 -- %s

Such usage, however, is not recommended.

The options can be stored in the configuration file (see CONFIGURATION below). The simplest configuration file will look like:

# Define the VCS type.
vcs-type cvs;
# Detach from the controlling terminal.
detach yes;
# Wait for the check in process to terminate.
sleep 2;
# Destination directory is located in this directory.
destination-root /srv/home;

Then the line in CVSROOT/loginfo can be simplified to:

ALL /bin/vcsync -- %p %s

The CVS synchronization routine gets the name of the project (the PROJECT part in the discussion above) from the value of the environment variable CVSROOT, by selecting its trailing directory component. For example, given the configuration file above and CVSROOT=/var/cvsroot/foo, the destination directory will be located in /srv/home/foo.

SVN
The utility must be configured as a post-commit hook. It expects the same arguments as the hook, i.e. path to the repository as the first argument, and revision string as the second one. Given the proper configuration file, it can be set up as:

$ cd repo/hooks
$ ln -sf /usr/bin/vcsync post-commit

The configuration file should then contain at least:

vcs-type svn;
destination-root /srv/home;

The vcs-type statement is optional. If missing, it will be detected automatically. See the section VCS DETECTION for details.

The project name is deduced from the first argument, by selecting its trailing directory component.

GIT
Vcsync must be invoked as git post-receive hook. For example:

$ cd repo.git/hooks
$ ln -s /usr/bin/vcsync post-receive

The simplest configuration file is:

vcs-type git;
destination-root /srv/home;

The vcs-type statement is optional. If missing, it will be detected automatically. See the section VCS DETECTION for details.

The project name is obtained from the last directory component of the current working directory (which is set by git to the repository being modified). The .git suffix will be removed.

OPTIONS

Operation mode
The options below are designed for testing and debugging purposes. They select a specific operation mode, and disable the usual vcsync behavior. Only one of them can be used in the command line.
-D, --checkoutrc=DIR

Run .checkoutrc file in directory DIR. If DIR ends with a slash, descend recursively into its subdirectories and process .checkoutrc files found there. See the section CHECKOUTRC below for a detailed discussion of .checkoutrc files and their purpose.

-t, --lint

Test configuration file syntax and exit.

Various settings
These options modify various configuration settings. They are equivalent to the eponymous configuration file statements and override these if present.
-T, --vcs-type=cvs|svn|git

Sets VCS type.

-b, --detach

Detach from controlling terminal after startup. This is mostly for use with CVS (together with the -s option).

-s, --sleep=NUMBER

Sleep NUMBER of seconds before doing the job.

-w, --destination-root=DIR

Defines destination root directory.

Logging and debugging
By default vcsync logs errors to the syslog facility user. The options below modify this behavior.
-d, --debug

Increase debug level.

-e, --stderr

Log everything to standard error instead of the syslog.

-l PRIO

Log everything with priority PRIO and higher to the stderr, as well as to the syslog.

-n, --dry-run

Do nothing, only print what would have been done.

Selecting configuration
The settings can be read from a configuration file (normally /etc/vcsync.conf, see the section CONFIGURATION for a detailed description of it). Two options are available to select the configuration settings to use:
-c, --config=FILE

Read configuration from FILE instead of the default location.

-N, --name=STRING

The configuration file can contain several sets of settings, called named configurations (see the description of the config statement in the CONFIGURATION section). This makes it possible to have single configuration file for use with different version control systems. The -N option is used to select the set to use.

Informational options
-V, --version

Print program version.

-h, --help

Print a short help summary.

--usage

Print a terse summary of the command line syntax.

-H, --config-help

Display help on the configuration file syntax.

CONFIGURATION

The program reads its configuration from the file /etc/vcsync.conf (the exact location can be changed at compilation time). Since most of the settings can be given in the command line, this file is optional and it is not considered an error if it does not exist (the warning about the fact is displayed if vcsync is run with the debugging level 1 or higher, though). An alternative configuration file can be specified using the -c (--config) command line option.

For a detailed description of the configuration file syntax and available statements, refer to vcsync.conf(5). The discussion below is but a concise summary of its statements.
debug number;

Sets the debug level.

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 execution timeout for a single VCS command, in seconds. The default 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 configurations
A named configuration is introduced by the following statement:

config name {
statements
}

where statements is a list of statements discussed above. This configuration takes effect (instead of the global configuration), if vcsync is invoked with the -N (--name) command line option whose argument matches the name in the config block. Named configurations are also used if the VCS type is not explicitly specified. See the section VCS DETECTION for details.

Logging
The following configuration statement controls the syslog output:

syslog {

facility user|daemon|auth|authpriv|mail|cron|local0-local7;
tag STRING;
print-priority BOOL;

}

VCS DETECTION

If the VCS type is not supplied explicitly (by the vcs-type configuration setting or the --vcs-type option), the program attempts to determine it by looking at the name with which it is invoked. If is able to correctly determine the VCS type, if it is being run from the hooks subdirectory of a git or SVN repository. Otherwise, it will assume the default VCS type.

When the VCS type is established, the program will look in the configuration file for the first named configuration that lists the detected type in its vcs-type statement and will use it. If no such configuration is found, the default one will be used.

Thus, a single configuration file can be used for all three supported version control systems.

CHECKOUTRC

A special feature is provided to use vcsync as a deployment engine for web pages. After synchronizing destination directory with the repository, it scans each updated directory for the presence of files named .htaccess and .checkoutrc. If .htaccess is found, it is removed. If .checkoutrc is found, it is read and processed line by line according to the following rules:

	1.		The # character introduces a comment. It and anything after it up to the nearest newline is removed.
	2.		Empty lines are ignored.
	3.		Non-empty lines must contain one of the following statements. The keywords are case-insensitive:

link src dst

Create a symbolic link from src to dst. Neither argument can be an absolute pathname or contain references to the parent directory.

unlink file

Unlink the file. The argument must refer to a file in the current directory or one of its subdirectories, that is either a symbolic link to another file or .htaccess file.

chmod mode file [file...]

Change mode of the listed files to mode, which must be an octal number. Shell wildcards are allowed in file arguments. After expandind, each file argument must refer to a file in the current directory or one of its subdirectories.

The administrator can also define additional keywords, as described in vcsync.conf(5), subsection Checkoutrc keywords. Appearance of these user-defined keywords in the .checkoutrc file cause creation and modification of the .htaccess file in the current directory.

The default configuration file shipped with the distribution defines the following keywords:
xbithack on|off

If set to on, adds the following to .htaccess:
Options +IncludesNOEXEC
XBitHack On

ssi on|off

If set to on, enables server-side includes, by adding the following statement to the .htaccess file:
AddHandler server-parsed .html

The following statements are reproduced in .htaccess verbatim:

redirect args...
rewritebase args...
rewritecond args...
rewriteengine args...
rewritemap args...
rewriteoptions args...
rewriterule args...

EXIT CODE

	0		Successful termination.
	1		Failure during synchronization.
	2		Command line usage error.
	3		Configuration file syntax error.

DOWNLOADS

Vcsync is available for download from this location.

The latest version is vcsync-1.3.

Recent news, changes and bugfixes can be tracked from the project's development page.

SEE ALSO

vcsync.conf(5), cvs(1), svn(1), git(1), githooks(5).

AUTHORS

Sergey Poznyakoff <gray@gnu.org>

BUG REPORTS

Report bugs to <bug-vcsync@gnu.org.ua>.

COPYRIGHT

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

---