initial commit

1 files changed, 133 insertions, 0 deletions

diff --git a/patches/README b/patches/README
new file mode 100644
index 0000000..cd4e12a
--- /dev/null
+++ b/patches/README
@@ -0,0 +1,133 @@
+ttym patches
+============
+
+Each patch is a unified diff against the pristine base. Apply with:
+
+    cd ttym
+    patch -p1 < patches/ttym-<name>-2.0.diff
+
+Then rebuild:
+
+    rm -f config.h ; make
+
+To get every feature at once, skip the individual patches entirely and
+apply ttym-full-2.0.diff -- one combined diff, no conflicts to resolve.
+See "The full build" below.
+
+
+The full build
+--------------
+
+  ttym-full-2.0.diff
+      Every feature in a single patch: persist-alert, flash, notify,
+      logging, hooks, bar-styles and config-file, with all inter-patch
+      conflicts already resolved. Apply it to the pristine base and
+      rebuild:
+
+          patch -p1 < patches/ttym-full-2.0.diff
+          rm -f config.h ; make
+
+      This is the recommended route to the full-featured build. It is
+      equivalent to stacking all seven feature patches below and hand-
+      resolving every collision, but deterministic and conflict-free.
+      Use the individual patches only when you want a specific subset.
+
+
+Available patches
+-----------------
+
+  ttym-persist-alert-2.0.diff
+      After a countdown completes, keep ringing the bell every ~1.5s
+      until any key is pressed. Foreground-only; backgrounded runs
+      fall through. Adds: --no-persist flag, ALERT_PERSIST knob.
+
+  ttym-flash-2.0.diff                              [requires persist-alert]
+      Add reverse-video terminal flash to the persistent alert loop.
+      Adds: --flash on|off flag, FLASH knob.
+
+  ttym-notify-2.0.diff
+      One-shot desktop notification and sound on countdown completion,
+      plus a MESSAGE positional argument piped through {title}/{msg}
+      placeholders. Adds: TITLE, NOTIFY_CMD, SOUND_CMD knobs.
+
+  ttym-logging-2.0.diff
+      TSV log at ~/.config/ttym/ttym.log, +tag extraction, the -r
+      reader (-n, --raw), and --stats (today|week|month|all). Adds
+      one-shot directory migration from ~/.config/timer/.
+      Adds: -c TEXT flag.
+
+  ttym-hooks-2.0.diff
+      Optional executables at ~/.config/ttym/hooks/{on_start,on_done,
+      on_quit} invoked with: mode duration_seconds comment.
+      Adds: -c TEXT flag (passed as 3rd hook arg).
+
+  ttym-bar-styles-2.0.diff
+      Eight built-in bar styles (unicode, ascii, hash, dots, line,
+      block, arrow, minimal) with locale-aware auto-detect.
+      Adds: --bar STYLE flag, BAR_STYLE knob.
+
+  ttym-config-file-2.0.diff               [capstone -- see Dependencies]
+      Runtime config at ~/.config/ttym/config (key = value), auto-
+      generated and self-documenting on first run. Exposes eight keys:
+      bar_fill, bar_empty, bar_style, flash, alert_persist, title,
+      notify_cmd, sound_cmd. A system-wide /etc/ttym.conf is read
+      first. Because it wires up knobs owned by other patches, it must
+      be applied LAST.
+
+
+Dependencies
+------------
+
+flash depends on persist-alert.
+
+config-file is the capstone: it reads knobs introduced by persist-
+alert, flash, notify, logging and bar-styles, and extends a usage()
+line added by hooks -- so all six must be applied before it. Apply
+config-file last.
+
+All other patches are independent of each other and of the base.
+
+
+Stacking
+--------
+
+The simplest route to the full build is ttym-full-2.0.diff (see "The
+full build" above). The notes here apply only when stacking the
+feature patches by hand to assemble a subset.
+
+Every patch in this directory applies and compiles cleanly against the
+pristine base -- except flash, which builds on persist-alert, and
+config-file, the capstone, which builds on six other patches (see
+Dependencies). That is the property the verification step guarantees.
+
+Combining multiple optional patches will produce conflicts at shared
+regions: the Config struct, usage(), the getopt() option string, and
+in some cases #include lines. This is normal suckless territory --
+resolve by hand, or apply ttym-full-2.0.diff instead. The base is laid
+out so most patches add their new code in fresh sections (before
+usage(), before main()) where they do not collide; the inevitable
+collisions are in points where every patch must add a line or field.
+
+Recommended order when stacking:
+
+    persist-alert  ->  flash  ->  notify  ->  logging  ->  hooks  ->
+    bar-styles     ->  config-file
+
+config-file must come last -- after bar-styles in particular, since it
+overrides the resolved bar glyphs. Apply, resolve any .rej files,
+rebuild.
+
+
+Authoring new patches
+---------------------
+
+Match the discipline used here:
+
+  - Add compile-time knobs to config.def.h, never inline in ttym.c.
+  - Update usage() in the same hunk as the option parser change, so
+    `timer -h` never drifts from what the build actually supports.
+  - Verify with `patch -p1` against a fresh copy of the base -- or,
+    for a patch with prerequisites, the base plus those -- and confirm
+    the result compiles before publishing.
+  - When the patch set changes, regenerate ttym-full-2.0.diff so the
+    one-shot full build stays in sync.