RERAT(8)

NAME

rerat — reminder rescheduler and archiver

SYNOPSIS

/usr/libexec/rerat [-n[n]] [-d date]

/usr/libexec/rerat -a

Re-schedules expired ratrun(8) Events from ~/.ratrun/old/ back to ~/.ratrun/ or archives them if they're old enough. With -n, doesn't, and lists what would be moved to the standard output stream (incl. the precise edits if -nn). -d overrides when "now" is.

With -a, runs rerat for all configured users: those limited to RATRUN_GROUPS, plus the individually-named RATRUN_USERS, who have a .ratrun/old directory in their home directory. Users are mailed with a summary of the errors (always) and motions (if verbose) for their run, if any.

Events

Are scanned for lines in the form (whitespace around the colon optional):

rerat : [word…]

from which field-split (white-space-delimited) configuration words are taken:

!|interval: re-schedule the event for the event date + interval; ! – don't re-schedule;
max=!|max: re-schedule the event no more than max times; ! – no limit (default);
reratted=count: counter maintained by rerat, count is incremented every time the event is re-scheduled;
original-time=…: the original event's date line (this skips the rest of the "rerat:" line);
archive=!|delay: move the event to arch after the event date + delay; ! – don't archive;
archive-name=arch: the file to save this event to, relative to ~/.ratrun/old/; arch is formatted via date(1) with the event date; the default is ".old";
[!]verbose: note the re-scheduling and archival of this event to the standard output stream (sent to the user by mail in -a mode); ! – be quiet (default);
[!]all: process all events (this is useful to enforce an archival policy for all events, for example); ! – just those with "rerat:" branding (default).

interval and delay use the Reminders format, recounted below.

Re-scheduled events, naturally, aren't archived.

Reminders

Start with a digit, are decimal integers, and optionally end with a recursively-expanded multiplicative suffix:

mo	=	4	wk
wk	=	7	d
yr	=	365	d
d	=	24	h
h	=	60	m
m	=	60
s	=	1

in this order, i.e. 10h = 600m = 36000 (= 36000s).

They correspond to the minimal time before the event, in seconds, to send a reminder — i.e. for reminders "3600 60 0" (equiv. "1h 1m 0"), a mail will be sent no sooner than an hour, a minute, and at the time of the event.

ENVIRONMENT

RERAT_DEFAULT: The default set of configuration words. Overriden per-user with .rerat and per-event with "rerat:" lines. [!]all is only meaningful when set here.
RATRUN_GROUPS: If non-empty, in -a mode, only check .ratrun presence for the specified groups. Field-split (white-space-delimited).
RATRUN_USERS: If non-empty, in -a mode, only check .ratrun presence for the specified users, or add them to the result from RATRUN_GROUPS. Field-split.
CONFDIR: Replaces "/etc/default" below.

FILES

/etc/default/ratrun: Sourced at the top.
~/.ratrun/old/: Scanned for expired Events produced by ratrun. Directory/hidden/unreadable/empty files are ignored.
~/.ratrun/: Re-scheduled events are moved here. If one already existed, its new name is appended with its date (à la 2022-11-02T04:44+01:00).
~/.ratrun/.rerat: Overrides RERAT_DEFAULT per-user, if present, providing a default configuration for all processed events. One field-split line.
~/.ratrun/.tz: If present, value exported as TZ per-user (cf. tzset(3)). One line.

EXAMPLES

Make the meeting with Henry weekly:

$ echo rerat :7d >> .ratrun/old/'meet henry in 201'

Schedule a daily reminder for two weeks, starting tomorrow at 9pm:

$ printf '%s\n' '2023-1-8 21:00' 'rerat: 1d max=13' > .ratrun/chrzęść

but abort it after a week:

$ echo rerat : ! >> .ratrun/chrzęść
$ tail -n2 .ratrun/chrzęść
rerat: 1d max=13 reratted=7 original-time=2023-1-8 21:00
rerat : !

Start archiving all events to ".{year}-Q{quarter}" (~/.ratrun/old/.2022-Q4, for example) after a quarter, except Robert-related ones; archive Henry-related ones to (".old") after a year:

$ tee -a .ratrun/*obert* .ratrun/old/*obert*
rerat: archive=!
^D
$ tee -a .ratrun/*enry* .ratrun/old/*enry*
rerat:archive=1yr archive-name=.old
^D
$ echo all archive=3mo archive-name=.%Y-Q%q > .ratrun/.rerat

(without the all word, only the events already containing a "rerat:" line would be subject to archival).

BUGS

Without all (or if archiving with pax/cpio; this is not the default), events in files with new-lines cannot be handled correctly. They aren't meaningful anyway, since mail subjects are single-line.