slug_watch(1)
=============

NAME
----
slug_watch - daemon to update PLD package refs on git push


SYNOPSIS
--------
[verse]
'slug_watch' -w <watchdir> -r <refrepodir> [<options>]
'slug_watch' -w <watchdir> -r <refrepodir> -d [start|stop]


DESCRIPTION
-----------

slug_watch is a server-side daemon that maintains the centralized Refs
repository used by linkgit:git-pld[1].  It watches a directory for
notification files written by gitolite post-receive hooks, and updates
the Refs repo and projects list accordingly.

When a developer pushes to a package repository, gitolite writes a
notification file to the watch directory.  slug_watch picks it up via
inotify, merges the updated refs into the Refs repo ('heads' file),
updates 'projects.list' for gitweb, and commits the change.

On startup, slug_watch processes any notification files already present
in the watch directory (sorted by mtime), then enters the inotify loop.


OPTIONS
-------

-w <directory>::
--watchdir <directory>::
    Directory to watch for notification files from gitolite hooks.
    Required.  If the path is not absolute, it is interpreted relative
    to the home directory of the user running the daemon.

-r <directory>::
--refrepodir <directory>::
    Directory containing the bare Refs git repository ('Refs.git').
    Required.  If the path is not absolute, it is interpreted relative
    to the home directory of the user running the daemon.

-d [start|stop]::
--daemon [start|stop]::
    Run as a daemon.  'start' forks into background and writes a PID
    file to '/var/run/slug_watch.pid'.  'stop' reads the PID file and
    sends SIGTERM.  If omitted, runs in foreground.

-u <user>::
--user <user>::
    Drop privileges to the specified user after starting.  Sets UID,
    GID, and HOME.

-m <address>::
--maillogs <address>::
    Send log messages via email to the specified address.  Repeatable
    for multiple recipients.  Requires '-s'.

-s <address>::
--sender <address>::
    Sender address for log emails.  Required when '-m' is used.


FILES
-----

/etc/sysconfig/slug_watch::
    Environment file for the systemd service.  Variables:
+
--
WATCHDIR;;
    Watch directory path.
REFREPODIR;;
    Refs repository directory path.
OTHER_OPTIONS;;
    Additional command-line options (e.g. '-m root -s git').
--

slug_watch.service::
    Systemd unit file.  Reads '/etc/sysconfig/slug_watch' and runs
    slug_watch as the 'git' user.

slug_watch-cron::
    Cron helper script that runs 'git gc' on the Refs repository.
    Typically scheduled every 15 minutes via crontab.

slug_watch.lock::
    Lock file (in the working directory) to prevent multiple instances.


EXIT STATUS
-----------

0::
    Clean shutdown (SIGTERM received).

1::
    Error (lock file held by another instance, or fatal exception).


SEE ALSO
--------

linkgit:git-pld[1]
