From 8543890f2e90af75a9bed7fa692ac92fc43285a4 Mon Sep 17 00:00:00 2001 From: Lukasz Kasprzak Date: Tue, 25 Aug 2026 19:35:46 +0200 Subject: hooks: replace the examples with ones that do what the binary cannot The previous examples largely duplicated features of the patched build. on_done sent a desktop notification and played a sound, both of which the notify patch already does, so a user who copied it got two of each. on_quit recorded abandoned sessions, but the logging patch calls write_log() unconditionally at the end of every run: abandoned sessions were already in the log behind timer -r. The new set does two things nothing else can: - Intent versus outcome. The log stores elapsed seconds only, so a finished 25m and an abandoned 30m that ran 25m are indistinguishable in it. The duration actually requested is visible to on_start and nowhere else, so the examples write START/DONE/QUIT records to $XDG_STATE_HOME/ttym/sessions.tsv. - Focus mode. During a countdown, pause dunst notifications and any playerctl/mpc playback; restore on done or quit. Countdown only, so a stopwatch cannot silence notifications indefinitely. A timewarrior bridge is included but commented out. Two behaviours documented in the file comments, both read off the code rather than assumed: notify_and_sound() runs before the on_done hook, so with dunst paused the completion popup is queued and appears when the hook unpauses -- delayed, not lost; and nothing restores dunst if the process is killed with -9. Every external command is guarded with command -v, so the examples degrade to the session record alone on a machine without those tools. Each hook works standalone -- the man page and README now say so explicitly, since installing only on_quit is a normal setup. All three pass sh -n and shellcheck, and were tested across all three paths: completed countdown, abandoned countdown, stopped stopwatch, with dunstctl is-paused confirmed false afterwards. Claude-Session: https://claude.ai/code/session_01APLBs8RB1FcUaC4viVkzbP --- timer.1 | 34 +++++++++++++++++++++++++++++++--- 1 file changed, 31 insertions(+), 3 deletions(-) (limited to 'timer.1') diff --git a/timer.1 b/timer.1 index e3fe0bc..e7850f9 100644 --- a/timer.1 +++ b/timer.1 @@ -256,6 +256,9 @@ or when a stopwatch is stopped. .PP A hook is any executable file at that name; there is nothing to enable. A file that is missing or not marked executable is skipped silently. +The three are independent: installing only +.BR on_quit , +for instance, is a complete and normal setup. .SS Arguments Each hook is run with exactly three positional arguments. .TP @@ -316,9 +319,34 @@ line like any other. Three commented, working examples ship with the source and are installed to .IR PREFIX/share/doc/ttym/hooks/ . -They set the terminal title, send a desktop notification and play a -sound on completion, and record abandoned sessions to a TSV file. Copy -the ones you want and edit: +They form one coherent set but each works alone. Together they do two +things the binary cannot: +.IP \(bu 2 +Record intent against outcome. The session log behind +.B timer \-r +stores elapsed seconds only, so a finished 25m and an abandoned 30m that +ran 25m look identical in it. The duration you asked for is visible to +.B on_start +and nowhere else, so the examples write a START/DONE/QUIT record to +.I $XDG_STATE_HOME/ttym/sessions.tsv +that shows follow\-through. +.IP \(bu 2 +Focus mode. During a countdown they pause +.BR dunst (1) +notifications and any +.BR playerctl (1) +or +.BR mpc (1) +playback, and restore both when it ends. Every external command is +guarded, so the examples are harmless on a machine without them. +.PP +A commented +.BR timew (1) +bridge is included but off by default; it turns +.B \-c +comments into timewarrior tags. +.PP +Copy the ones you want and edit: .PP .RS .nf -- cgit v1.3