.TH mswatch 1
..
.SH NAME
mswatch \- watch mailstores for changes and initiate mailbox syncs
..
.SH SYNOPSIS
\fBmswatch\fR [\fIoptions\fR ...]
..
.SH DESCRIPTION
\fBmswatch\fR is a command line program that makes keeping two
mailboxes synchronized \fIfaster\fR and \fImore efficient\fR than
periodically synchronizing the two mailboxes.

\fBmswatch\fR watches mailboxes to know when to initiate mailbox syncs.
Using mswatch, your mail synchronization program can be called on
demand instead of through polling, resulting in prompter mail delivery
and lower bandwidth usage and server load.
..
.SH OPTIONS
.TP
\fB\-c\fR file, \fB\-\-config=\fRfile
Read configuration from \fIfile\fR.
By default, the configuration is read from ~/.mswatchrc.
..
.TP
\fB\-d\fR, \fB\-\-dry\fR
Watch mailstores for changes but do not initiate syncs.
.TP
\fB\-q\fR, \fB\-\-quiet\fR
Do not print success status messages.
.TP
\fB\-V\fR, \fB\-\-version\fR
Display version information.
.TP
\fB\-?\fR, \fB\-\-help\fR
Display a summary of command line options.
..
.SH SIGNALS
..
.TP
\fBSIGUSR1\fR
Print names of mailboxes with pending syncs.
..
.TP
\fBSIGINT\fR and \fBSIGTERM\fR
Gracefully exit.
..
.SH CONFIGURATION
The configuration file is mandatory; \fBmswatch\fR will not run without it.
Text starting with a hash mark (#) through the end of the current line are
comments and are ignored. Spaces and tabs delimit.
..
.TP
\fBbase_delay\fR \fItime\fR
Default: 10 seconds
.br
Minimum time after first queued mailbox change to synchronization.
..
.TP
\fBinter_delay\fR \fItime\fR
Default: 60 seconds
.br
Minimum time between two synchronizations or failed attempts (this is
the default inter_delay setting for mailboxes).
..
.TP
\fBinter_delay\fR \fItime\fR \fImailboxes ...\fR
Default: inter_delay
.br
Minimum time between two synchronizations or failed attempts for the
list mailboxes.
..
.TP
\fBmax_delay\fR \fItime\fR
Default: 600 seconds
.br
Maximum waiting time between failed attempts.
..
.TP
\fBpoll_period\fR \fItime\fR
Default: 86400 seconds (1 day)
.br
Period at which to poll all mailboxes. This option is for use with sync
programs that can error without returning a failed status---it ensures that
the mailboxes are at least this fresh. To disable polling, set the period
to 0.
..
.TP
\fBignore\fR \fImailboxes ...\fR
Optional
.br
Do not initiate explicit synchronizations for these mailboxes. mswatch will
ignore changes made to these mailboxes while it is running, but will still
synchronize them at start when all mailboxes are synchronized.
..
.TP
\fBsync\fR \fIprogram arguments ...\fR
Required
.br
Program and arguments to run to synchronize mail stores. Mailbox names
are appended to \fIarguments ...\fR when \fIprogram\fR is run.
..
.TP
\fBmailbox_prefix\fR \fIprefix\fR \fIseparator\fR
Optional
.br
Prefix these strings to mailbox names passed to \fBsync\fR; useful when using
\fBmbsync\fR for \fBsync\fR, as the \fBmbsync\fR channel.
If present, \fIprefix\fR is always prefixed to mailbox names.
When synchronizing a particular mailbox, \fIseparator\fR is inserted between \fIprefix\fR and the mailbox name
(\fIseparator\fR is not inserted when synchronizing all mailboxes).
.br
Examples:
.br
Given \fIprefix\fR = "mydomain" and \fIseparator\fR = ":" and
that the mailbox "INBOX" is to be synchronized, "mydomain:INBOX" is passed
to \fBsync\fR.
.br
Given \fIprefix\fR = "mydomain" and \fIseparator\fR = ":" and
that all mailboxes are to be synchronized, "mydomain" is passed
to \fBsync\fR.
..
.TP
\fBstore\fR \fIname\fR { \fBwatch\fR \fIprogram arguments ...\fR }
Required (two stores)
.br
A mailstore to watch. Call it \fIname\fR when reporting status information
to the user. \fBwatch\fR sets the program and arguments to run the
mailstore watcher. \fBwatch_maildirs\fR(1) is a Maildir mailstore watcher.
..
.SH FILES
.TP
.B ~/.mswatchrc
Default configuration file
..
.SH SEE ALSO
.BR inputkill (1),
.BR watch_maildirs (1),
.BR socketwatch (1),
.BR mbsync (1),
.P
mswatch website: http://mswatch.sf.net/
..
.SH AUTHOR
Written by Chris Frost <chris@frostnet.net>.