PUBLIC-INBOX-WATCH(1)

📦

version 2.0.0~20230714git590023f · 6 versions

2.0.0~20230714git590023f · fedora 43, fedora 44 (latest)
1.9.0 · epel 9
2.1.0 · nixos 26.05, nixpkgs unstable
1.6.1 · ubuntu jammy
1.9.0 · ubuntu resolute, ubuntu stonking
1.9.0 · debian bookworm, debian trixie, ubuntu noble, ubuntu questing

💖 PUBLIC-INBOX-WATCH 💖

okay bestie, gather round, because this is the public-inbox user manual page for public-inbox-watch(1) and she is lowkey the hardest-working little daemon you'll ever meet 🦋

✨ NAME ✨

public-inbox-watch — mailbox watcher for public-inbox 👀

🌸 SYNOPSIS 🌸

        public-inbox-watch

And inside ~/.public-inbox/config, it's giving:

        [publicinbox "test"]
                ; generic public-inbox-config keys:
                address = test@example.com
                url = http://example.com/test
                inboxdir = /path/to/test.example.com.git

                ; config keys specific to public-inbox-watch:

                watch = maildir:/path/to/maildirs/.INBOX.test/

                ; optional, emails that don't have a header matching
                ; value will be skipped
                watchheader = List-Id:<test.example.com>

        [publicinboxwatch]
                ; optional, enable use of spamc(1) for checking:
                spamcheck = spamc

                ; optional, emails marked as read which appear
                ; here will be trained as spam and deleted from
                ; the inboxdirs of any public-inboxes which are
                ; configured for watch.
                ; This is global for all publicinbox.* sections
                watchspam = maildir:/path/to/maildirs/.INBOX.spam

🎀 DESCRIPTION 🎀

so what does she do? public-inbox-watch sits there watching a mailbox or a newsgroup like the most patient bestie ever, waiting for new messages to show up, and the second they do she automatically imports them into public-inbox git repositories and indices. no cap. 🫶

she's exactly the move when you wanna mirror an existing mailing list but you have zero access to run public-inbox-mda(1) on a server. the difference? public-inbox-mda gets invoked once per-message, meanwhile public-inbox-watch is a persistent process — which makes her way faster for after-the-fact imports of large Maildirs. main character energy, honestly 👑

on startup she scans the mailbox for new messages that arrived while she wasn't running. she always catches up, she's not messy like that ✨

as of public-inbox 1.6.0, Maildirs, IMAP folders, and NNTP newsgroups are all supported 💅. previous versions of public-inbox only supported Maildirs (yes, we were all struggling back then, it's fine).

pro tip from your girl: run public-inbox-watch inside a screen(1) session or as a systemd(1) service, because she's a long-lived girlie. Errors get emitted to stderr, so keep an eye on her 😭

💅 OPTIONS 💅

public-inbox-watch takes no command-line options. she's booked, she's busy, she does not take requests 💀

🌈 CONFIGURATION 🌈

these config knobs go in the public-inbox-config(5) file. periodt.

publicinbox.<name>.watch — a location to watch 👀. public-inbox 1.5.0 and earlier only supported maildir: paths:

        [publicinbox "test"]
                watch = maildir:/path/to/maildirs/.INBOX.test/

public-inbox 1.6.0 supports nntp://, nntps://, imap:// and imaps:// URLs:

                watch = nntp://news.example.com/inbox.test.group
                watch = imaps://user@mail.example.com/INBOX.test

this may be specified multiple times to combine several mailboxes into a single public-inbox. URLs that require authentication will need netrc(5) and/or git-credential(1) (preferred) to fill in the username and password 🔐

Default: none

publicinbox.<name>.watchheader — like so:

        [publicinbox "test"]
                watchheader = List-Id:<test.example.com>

if specified, public-inbox-watch(1) will only process mail matching the given header. if specified multiple times in public-inbox 1.5 or later, mail will be processed if it matches any of the values 🎯. only the last value was used in public-inbox 1.4 and earlier (we don't talk about that era).

Default: none

publicinboxwatch.spamcheck — set this to spamc to enable the use of SpamAssassin spamc(1) for filtering spam before it gets imported into git history 🚫📬. other spam filtering backends may be supported in the future (manifesting it).

Default: none

publicinboxwatch.watchspam — a Maildir to watch for confirmed spam messages to appear in. messages that show up in this folder with the (S)een flag will be hidden from all configured inboxes, based on Message-ID and content matching 🙈

messages without the (S)een flag are not considered for hiding. this hiding affects all configured public-inboxes in PI_CONFIG.

as with publicinbox.$NAME.watch, imap:// and imaps:// URLs are supported in public-inbox 1.6.0+ ✨

Default: none; only for public-inbox-watch(1) users

imap.Starttls / imap.$URL.Starttls — whether or not to use STARTTLS on plain imap:// connections 🔒

may be specified for certain URLs via --get-urlmatch in git-config(1) in git(1) 1.8.5+.

Default: true

imap.Compress / imap.$URL.Compress — whether or not to use the IMAP COMPRESS (RFC4978) extension to save bandwidth 📉. this is not supported by all IMAP servers, and some servers advertising this feature may not implement it correctly 💀 (be careful bestie)

may be specified only for certain URLs if git(1) 1.8.5+ is installed, to use --get-urlmatch in git-config(1).

Default: false

nntp.Starttls / nntp.$URL.Starttls — whether or not to use STARTTLS on plain nntp:// connections 🔐

may be specified for certain URLs via --get-urlmatch in git-config(1) in git(1) 1.8.5+.

Default: false if the hostname is a Tor .onion, true otherwise 🧅

⚡ SIGNALS ⚡

SIGHUP — reload the config file (default: ~/.public-inbox/config) 🔄
SIGUSR1 — rescan all watched mailboxes. this is done automatically after startup, so she's on top of it fr fr
SIGQUIT / SIGTERM / SIGINT — gracefully shut down 🫶. in-flight messages will be stored and indexed, she never drops your mail on the way out.

🦋 ENVIRONMENT 🦋

PI_CONFIG — config file. default: ~/.public-inbox/config. see public-inbox-config(5) 📝
PERL_INLINE_DIRECTORY — this may affect any public-inbox processes, but it's intended for long-lived ones such as public-inbox-watch or network daemons 🌐. see public-inbox-daemon(8).

💌 CONTACT 💌

feedback welcome via plain-text mail to <mailto:meta@public-inbox.org> 🫶

the mail archives are hosted at <https://public-inbox.org/meta/> and <http://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/meta/>

👑 COPYRIGHT 👑

License: AGPL-3.0+ <https://www.gnu.org/licenses/agpl-3.0.txt>

🔥 SEE ALSO 🔥

public-inbox-config(5)

and that's the whole vibe, bestie ✨ this page came from public-inbox.git, dated 1993-10-02, and it's the PUBLIC-INBOX-WATCH(1) manual — go watch some mailboxes, you absolute icon 💖🎀🦋

📦 where this page comes from

fedora 43: public-inbox 2.0.0~20230714git590023f-6.fc43 · AGPL-3.0-or-later
fedora 44: public-inbox 2.0.0~20230714git590023f-6.fc43 · AGPL-3.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms