.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "SYSGATHER 1"
.TH SYSGATHER 1 "2008-01-14" "perl v5.8.8" "User Contributed Perl Documentation"
.SH "NAME"
sysgather \- a configuration file mismanager
.PP
$Ringlet: sysgather.pl 1027 2007\-02\-27 09:47:40Z roam $
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  sysgather [-hnqvV] [-f file] command [package...]
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The \fBsysgather\fR utility stores various collections of configuration files,
both for the system and for applications, in order to facilitate keeping
them under version control.
.PP
The configuration files are organized into collections, or packages.
Each package is defined by a section in the \fBsysgather.conf\fR file.
An example of a package could be the base system configuration files
(most of the contents of the /etc directory), the Apache webserver
configuration files (httpd.conf, access.conf, mime.types, etc.), or
a user's dotfiles.
.PP
If the special value \f(CW\*(C`ALL\*(C'\fR is specified as the only package name,
\&\fBsysgather\fR operates on \fBall\fR the groups defined on the \f(CW\*(C`groups\*(C'\fR
line in the \f(CW\*(C`default\*(C'\fR section of its configuration file.
.PP
The \fBsysgather\fR utility processes two configuration files: a system-wide
one, located in \fI/usr/local/etc/sysgather.conf\fR, and a per-user file
containing additional definitions and overrides, located in each user's
home directory and named \fI.sysgather.conf\fR.  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 \f(CW\*(C`default\*(C'\fR section
will also replace the corresponding variables from the system-wide file.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fB\-f\fR \fIfile\fR" 4
.IX Item "-f file"
Specify the configuration file to use instead of the default
\&\fB/usr/local/etc/sysgather.conf\fR.
.Sp
\&\fBNote:\fR If this option is present, the \fI~/.sysgather.conf\fR file
is \fBnot\fR processed after the specified configuration file.
.IP "\fB\-h\fR" 4
.IX Item "-h"
Display usage information and exit.
.IP "\fB\-n\fR" 4
.IX Item "-n"
For the \fBdiff\fR, \fBget\fR, and \fBput\fR commands, do not actually copy
any files or execute any system commands, but simply report what would
have been done.
.IP "\fB\-q\fR" 4
.IX Item "-q"
Quiet operation \- suppress informational and warning messages, only
complain about genuine error conditions.
.IP "\fB\-V\fR" 4
.IX Item "-V"
Display the program version and exit.
.IP "\fB\-v\fR" 4
.IX Item "-v"
Verbose operation \- display progress messages during the program's work.
.SH "COMMANDS"
.IX Header "COMMANDS"
The \fBsysgather\fR utility recognizes the following commands:
.IP "* \fBdiff\fR" 4
.IX Item "diff"
Show the differences between the stored and current config files.
.IP "* \fBdiffsource\fR (or \fBdiffsrc\fR)" 4
.IX Item "diffsource (or diffsrc)"
Show the differences between the stored and current original (vendor)
versions of the config files.
.IP "* \fBget\fR" 4
.IX Item "get"
Fetch the current versions of the config files.
.IP "* \fBhelp\fR" 4
.IX Item "help"
Display usage instructions and exit.
.IP "* \fBput\fR" 4
.IX Item "put"
Install the working copies of the config files to their real locations.
.IP "* \fBsource\fR (or \fBsrc\fR)" 4
.IX Item "source (or src)"
Fetch the original (vendor) versions of the config files.
.IP "* \fBversion\fR" 4
.IX Item "version"
Display the program version and exit.
.SH "CONFIGURATION FILE SYNTAX"
.IX Header "CONFIGURATION FILE SYNTAX"
The configuration file for the \fBsysgather\fR utility usually goes by the name
of \fBsysgather.conf\fR.  It is separated into several sections, of which only
one is mandatory \- the \fIdefault\fR section.
.Sh "\s-1THE\s0 \fIdefault\fP \s-1SECTION\s0"
.IX Subsection "THE default SECTION"
Currently, the \fIdefault\fR section only contains one setting: the \fIgroups\fR
variable, a list of file collections for \fBsysgather\fR to process.  For each
name in this list, \fBsysgather\fR looks for a configuration file section by
the same name, and treats it as a file collection section.
.Sh "\s-1FILE\s0 \s-1COLLECTION\s0 \s-1SECTIONS\s0"
.IX Subsection "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.
.PP
There are two modes of \fBsysgather\fR operation \- source files and actual
files.  The files listed in the \f(CW\*(C`files\*(C'\fR property are the actual files
that will be kept track of.  For some of them, a source file may be
specified \- an \*(L"original\*(R", vendor version.  This may be useful for
keeping track of local changes and merging the vendor modifications
across upgrades.
.PP
For each collection, the following configuration directives may be
specified:
.IP "* basedir" 4
.IX Item "basedir"
The directory where the files from this collection will be stored by
sysgather.
.IP "* confdir" 4
.IX Item "confdir"
The directory where the actual files from this collection are to be
found on the system.
.IP "* srcdir" 4
.IX Item "srcdir"
The directory where the source (vendor) copies of the files are to
be found on the system.
.Sp
If a package does not provide default versions of any files, the
\&\f(CW\*(C`srcdir\*(C'\fR property may be specified as \f(CW\*(C`NONE\*(C'\fR and \fBsysgather\fR will
refuse to execute the \f(CW\*(C`source\*(C'\fR and \f(CW\*(C`diffsource\*(C'\fR commands on this
collection.
.IP "* files" 4
.IX Item "files"
The actual files comprising this collection.  Those may be specified as
simple filenames within \f(CW\*(C`confdir\*(C'\fR, paths relative to \f(CW\*(C`confdir\*(C'\fR, or
absolute paths.
.PP
For each of the actual files listed in the \f(CW\*(C`files\*(C'\fR directive, a source
file may be specified.  This is done by defining a \f(CW\*(C`property\*(C'\fR with
the same name as the actual file, the value of which is the name of
the source file relative to \f(CW\*(C`srcdir\*(C'\fR.
.PP
For an example, please consult the various configuration files in
the \fI/usr/local/share/examples/sysgather/\fR directory, as well as
the sample \fIsysgather.conf\fR file provided with the \fBsysgather\fR
distribution.
.SH "FILES"
.IX Header "FILES"
.IP "\fI/usr/local/etc/sysgather.conf\fR" 4
.IX Item "/usr/local/etc/sysgather.conf"
The default configuration file, unless overridden by the \fB\-f\fR command-line
option.
.IP "\fI~/.sysgather.conf\fR" 4
.IX Item "~/.sysgather.conf"
The per-user configuration file, located in the home directory of the
account invoking \fBsysgather\fR.  The contents of this file is merged with
the contents of the system-wide file as described above.
.IP "\fI/usr/local/share/examples/sysgather/*.conf\fR" 4
.IX Item "/usr/local/share/examples/sysgather/*.conf"
Sample configuration files.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Grab the base system's default configuration files for an import into
a version control system:
.PP
.Vb 1
\&  sysgather source sys-fbsd5
.Ve
.PP
Fetch the currently-used versions of the system files and the Apache
webserver configuration for a check-in into the version control system:
.PP
.Vb 1
\&  sysgather get sys-fbsd5 apache
.Ve
.PP
Display the differences between the stored files and the currently active
Apache configuration:
.PP
.Vb 1
\&  sysgather diff apache
.Ve
.PP
Put the stored configuration files (presumably after a version control
check\-in) as the active configuration for the Apache webserver:
.PP
.Vb 1
\&  sysgather put apache
.Ve
.SH "BUGS"
.IX Header "BUGS"
.IP "\(bu" 4
There is no \fB\-O\fR \fIoption=value\fR command-line option.
.IP "\(bu" 4
This documentation is much too sketchy.
.IP "\(bu" 4
There is no test suite.
.SH "HISTORY"
.IX Header "HISTORY"
The \fBsysgather\fR utility was written by Peter Pentchev in 2005.
.SH "AUTHOR"
.IX Header "AUTHOR"
Peter Pentchev <roam@ringlet.net>