$Ringlet: sysgather.pl 1027 2007-02-27 09:47:40Z roam $

SYNOPSIS

         sysgather [-hnqvV] [-f file] command [package...]

DESCRIPTION

       The sysgather utility stores various collections of configuration
       files, both for the system and for applications, in order to facilitate
       keeping them under version control.

       The configuration files are organized into collections, or packages.
       Each package is defined by a section in the sysgather.conf file.  An
       example of a package could be the base system configuration files (most
       of the contents of the /etc directory), the Apache webserver configura-
       tion files (httpd.conf, access.conf, mime.types, etc.), or a user's
       dotfiles.

       If the special value "ALL" is specified as the only package name, sys-
       gather operates on all the groups defined on the "groups" line in the
       "default" section of its configuration file.

       The sysgather utility processes two configuration files: a system-wide
       one, located in /usr/local/etc/sysgather.conf, and a per-user file con-
       taining additional definitions and overrides, located in each user's
       home directory and named .sysgather.conf.  If the per-user file exists,
       any collections defined within it replace the corresponding collections
       from the system-wide file, and any variables in the "default" section
       will also replace the corresponding variables from the system-wide
       file.

OPTIONS

       -f file
           Specify the configuration file to use instead of the default
           /usr/local/etc/sysgather.conf.

           Note: If this option is present, the ~/.sysgather.conf file is not
           processed after the specified configuration file.

       -h  Display usage information and exit.

       -n  For the diff, get, and put commands, do not actually copy any files
           or execute any system commands, but simply report what would have
           been done.

       -q  Quiet operation - suppress informational and warning messages, only
           complain about genuine error conditions.

       -V  Display the program version and exit.

       -v  Verbose operation - display progress messages during the program's
           work.

           Display usage instructions and exit.

       * put
           Install the working copies of the config files to their real loca-
           tions.

       * source (or src)
           Fetch the original (vendor) versions of the config files.

       * version
           Display the program version and exit.

CONFIGURATION FILE SYNTAX

       The configuration file for the sysgather utility usually goes by the
       name of sysgather.conf.  It is separated into several sections, of
       which only one is mandatory - the default section.

       THE default SECTION

       Currently, the default section only contains one setting: the groups
       variable, a list of file collections for sysgather to process.  For
       each name in this list, sysgather looks for a configuration file sec-
       tion by the same name, and treats it as a file collection section.

       FILE COLLECTION SECTIONS

       A file collection is, simply put, a list of files to keep under version
       control together.  Each collection is represented by a INI-style group
       - the name of the group serves as the name of the collection.  There
       are two kinds of variables within the group - collection properties and
       source file specifications.

       There are two modes of sysgather operation - source files and actual
       files.  The files listed in the "files" property are the actual files
       that will be kept track of.  For some of them, a source file may be
       specified - an "original", vendor version.  This may be useful for
       keeping track of local changes and merging the vendor modifications
       across upgrades.

       For each collection, the following configuration directives may be
       specified:

       * basedir
           The directory where the files from this collection will be stored
           by sysgather.

       * confdir
           The directory where the actual files from this collection are to be
           found on the system.

       * srcdir
           The directory where the source (vendor) copies of the files are to

       same name as the actual file, the value of which is the name of the
       source file relative to "srcdir".

       For an example, please consult the various configuration files in the
       /usr/local/share/examples/sysgather/ directory, as well as the sample
       sysgather.conf file provided with the sysgather distribution.

FILES

       /usr/local/etc/sysgather.conf
           The default configuration file, unless overridden by the -f com-
           mand-line option.

       ~/.sysgather.conf
           The per-user configuration file, located in the home directory of
           the account invoking sysgather.  The contents of this file is
           merged with the contents of the system-wide file as described
           above.

       /usr/local/share/examples/sysgather/*.conf
           Sample configuration files.

EXAMPLES

       Grab the base system's default configuration files for an import into a
       version control system:

         sysgather source sys-fbsd5

       Fetch the currently-used versions of the system files and the Apache
       webserver configuration for a check-in into the version control system:

         sysgather get sys-fbsd5 apache

       Display the differences between the stored files and the currently
       active Apache configuration:

         sysgather diff apache

       Put the stored configuration files (presumably after a version control
       check-in) as the active configuration for the Apache webserver:

         sysgather put apache

BUGS

       o   There is no -O option=value command-line option.

       o   This documentation is much too sketchy.

       o   There is no test suite.

HISTORY

       The sysgather utility was written by Peter Pentchev in 2005.