diff --git a/COMPAT.md b/COMPAT.md index e25911f..494cc74 100644 --- a/COMPAT.md +++ b/COMPAT.md @@ -10,6 +10,7 @@ on the same invocations. | | | |---|---| | commands | `failed STATUS NAME LOGDIR [TMP_LOGDIR]`, `rotate ROOT --compress-after DAYS [--delete-after DAYS] [--lock-timeout SECONDS]`, `-h`, `--help`, `--version` | +| usage | the same text on stdout for `-h`, `--help` and no arguments | | exit codes | 0 on success and on every `failed` that got past its arguments; 2 for a refused invocation, after `eb-keep-logs: MESSAGE` on stderr; 2 with the usage text on stdout for no arguments; 75 when another `rotate` holds ROOT's lock past `--lock-timeout`, after `eb-keep-logs: another rotate holds the lock ROOT/.eb-keep-logs-rotate.lock; gave up after N s (--lock-timeout)` on stderr | | one rotate at a time | `rotate` holds an exclusive flock(2) on `ROOT/.eb-keep-logs-rotate.lock`, created when missing, from before it reads ROOT until it exits; it waits up to `--lock-timeout` seconds for it, 600 without the option or with an empty value, 0 not at all, 999999999 at most; it opens the file for reading when it may not write it; a lock file that cannot be opened, or a symbolic link or non-regular file at its name, is refused, exit 2; on a file system that cannot lock, `rotate` says so on stderr and rotates without the lock | | environment | `PATH` (finds `eb`), `EASYBUILD_TMPDIR`, `EB_KEEP_LOGS_NOW`, `EB_PIPELINE_LOG_DIR`, `TZ`, `TZDIR` | @@ -24,7 +25,6 @@ on the same invocations. | case | shell script | Zig build | |---|---|---| -| no arguments, `--help` | prints a trailing half sentence from the script's header | stops after the `--version` line | | `--version` | `eb-keep-logs 0.1.0` | `eb-keep-logs 0.2.1 (TARGET, MODE, zig VERSION, COMMIT)`; the first two words are unchanged | | `--compress-after` or `--delete-after` with no value after it | never returns | refused, exit 2 | | `EB_KEEP_LOGS_NOW` not empty and not an integer | evaluated as shell arithmetic | refused, exit 2 | diff --git a/README.md b/README.md index 936fd80..af64596 100644 --- a/README.md +++ b/README.md @@ -79,8 +79,8 @@ eb-keep-logs rotate /srv/build-logs --compress-after 30 --delete-after 365 ``` `rotate` looks only at run directories named `YYYYMMDD_HHMMSS` directly under the root, and dates each run by its name. -It gzips the `*.log` and `*.txt` files of runs older than `--compress-after` days, keeps each file's mode, and updates the run's `.licensed-logs`, writing each new list beside the old one and renaming it over it. -It removes whole runs older than `--delete-after` days only when that option is given. +It gzips the `*.log` and `*.txt` files of runs at least `--compress-after` days old, keeps each file's mode, and updates the run's `.licensed-logs`, writing each new list beside the old one and renaming it over it. +It removes whole runs at least `--delete-after` days old only when that option is given. It leaves alone the run it writes into, which is still going: the run that holds its standard output or error, and the run that holds `EB_PIPELINE_LOG_DIR`, the log directory `eb-pipeline` exports, because srun passes the output on over a pipe. It also leaves alone every run that a process on the same host has a file in open for writing, as a build that is still going has its log, whichever run started the rotation: it finds them in `/proc/PID/fd`, for the processes whose descriptors it may read. A later `rotate` takes such a run. diff --git a/changelog.d/+help-reference.doc.md b/changelog.d/+help-reference.doc.md new file mode 100644 index 0000000..4106812 --- /dev/null +++ b/changelog.d/+help-reference.doc.md @@ -0,0 +1 @@ +The command-line reference shows the usage that `-h`, `--help` and no arguments print, which the suite checks against both builds, and its synopsis and exit statuses name `-h`. README.md says that `rotate` compresses and removes the runs at least DAYS old, as the usage and the reference do. diff --git a/changelog.d/+help-text.bugfix.md b/changelog.d/+help-text.bugfix.md new file mode 100644 index 0000000..38d05f3 --- /dev/null +++ b/changelog.d/+help-text.bugfix.md @@ -0,0 +1 @@ +`--help`, `-h` and no arguments print the whole usage, the same in both builds: the shell script no longer ends it with a blank line and half a sentence of its own header. It lists every option, `-h` and the `--OPTION=VALUE` forms included, with what each of `rotate`'s options defaults to (600 seconds for `--lock-timeout`), the environment variables the commands read and the exit statuses 0, 2 and 75, and it says that `rotate` takes the runs at least DAYS old, not the runs older than DAYS. COMPAT.md lists the usage as kept, no longer as a deliberate difference. diff --git a/docs/orgmode/reference/cli.org b/docs/orgmode/reference/cli.org index c94e774..a2b1f91 100644 --- a/docs/orgmode/reference/cli.org +++ b/docs/orgmode/reference/cli.org @@ -12,7 +12,8 @@ This page describes the Zig build; the shell script =eb-keep-logs= in the reposi #+begin_example eb-keep-logs failed STATUS NAME LOGDIR [TMP_LOGDIR] eb-keep-logs rotate ROOT --compress-after DAYS [--delete-after DAYS] [--lock-timeout SECONDS] -eb-keep-logs --help | --version +eb-keep-logs -h | --help +eb-keep-logs --version #+end_example ** Arguments @@ -56,7 +57,7 @@ eb-keep-logs --help | --version | Status | Meaning | |--------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| 0 | =--help= or =--version=, a =failed= that accepted its arguments, or a =rotate= that accepted its arguments and did not give up waiting for its lock, whatever it could keep, compress or remove: what it could not do is reported, and is no failure. | +| 0 | =-h=, =--help= or =--version=, a =failed= that accepted its arguments, or a =rotate= that accepted its arguments and did not give up waiting for its lock, whatever it could keep, compress or remove: what it could not do is reported, and is no failure. | | 2 | The invocation was refused, with =eb-keep-logs: MESSAGE= on stderr; or no command was given, and the usage is on stdout. | | 75 | Another =rotate= held =ROOT='s lock for longer than =--lock-timeout=, and this =rotate= changed nothing; try again later. | @@ -162,6 +163,66 @@ What =rotate= cannot do it reports on stderr as =eb-keep-logs: MESSAGE=, and goe | =cannot sync a .licensed-logs: ERROR= | A list was replaced, but its directory could not be synced; after a crash the old list may be back. | | =cannot delete ROOT/RUN: ERROR= | The run could not be removed completely; what was removed stays removed. | +*** --help + +The usage =-h=, =--help= and no arguments print on stdout, the same from the shell script: + +#+begin_example +eb-keep-logs: keep the logs of EasyBuild builds that a build pipeline would +otherwise lose, and keep the pipeline's log tree bounded. + + eb-keep-logs failed STATUS NAME LOGDIR [TMP_LOGDIR] + After `eb` returned STATUS for easyconfig NAME: when STATUS is not 0, + copy the EasyBuild session log `eb --last-log` names, the failing + command's output and a meson testlog next to LOGDIR/NAME.stdout.log, + closed to others and listed in LOGDIR/.licensed-logs. TMP_LOGDIR is + the --tmp-logdir eb ran with; without it, the newest log in + EasyBuild's default place is used, unless it is another build's. + NAME.stdout.log and a TMP_LOGDIR below LOGDIR are closed to others too. + eb-keep-logs rotate ROOT --compress-after DAYS [--delete-after DAYS] + [--lock-timeout SECONDS] + In the run directories directly under ROOT (named YYYYMMDD_HHMMSS), + gzip the *.log and *.txt files of old runs and remove older runs + whole, leaving alone a run that is still written into. A run's age is + in days from the local midnight of the date in its name. Permissions + and .licensed-logs follow. One rotate of ROOT runs at a time, holding + ROOT/.eb-keep-logs-rotate.lock. Options and ROOT come in any order. + --compress-after DAYS, --compress-after=DAYS + Gzip the files of runs at least DAYS old. Required; there is no + default. + --delete-after DAYS, --delete-after=DAYS + Remove whole runs at least DAYS old; DAYS must be larger than + that of --compress-after. Default: none; no run is removed. An + empty value is the default. + --lock-timeout SECONDS, --lock-timeout=SECONDS + While another rotate holds the lock, wait up to SECONDS for it, + then give up and exit 75. Default: 600; 0 does not wait. An empty + value is the default. + eb-keep-logs -h | --help + Print this help on stdout and exit 0. + eb-keep-logs --version + Print the version line on stdout and exit 0. + +Environment: + PATH Where failed looks up eb. + EASYBUILD_TMPDIR failed copies a command's output only from below it; + unset or empty, it copies none. + EB_KEEP_LOGS_NOW The time rotate takes as now, in seconds since the + epoch; unset or empty, the current time. + EB_PIPELINE_LOG_DIR rotate leaves alone the run that holds this path. + TZ, TZDIR The time zone of the local midnights, and the + directory of zone files. + +Exit status: + 0 -h, --help or --version, or a failed or rotate that accepted its + arguments, whatever it could keep, compress or remove: what it could + not do is reported on stderr. + 2 The invocation was refused, with eb-keep-logs: MESSAGE on stderr; or + no command was given, and this help is on stdout. + 75 rotate waited --lock-timeout seconds for the lock another rotate + held, then gave up and changed nothing; run it again later. +#+end_example + *** --version The version line follows the [[site:zig-common:reference/cli-conventions][command-line conventions]] of the stackhands Zig tools. diff --git a/eb-keep-logs b/eb-keep-logs index b83312e..13f1071 100755 --- a/eb-keep-logs +++ b/eb-keep-logs @@ -2,24 +2,6 @@ # eb-keep-logs: keep the logs of EasyBuild builds that a build pipeline would # otherwise lose, and keep the pipeline's log tree bounded. # -# eb-keep-logs failed STATUS NAME LOGDIR [TMP_LOGDIR] -# After `eb` returned STATUS for easyconfig NAME: when STATUS is not 0, -# copy the EasyBuild session log `eb --last-log` names, the failing -# command's output and a meson testlog next to LOGDIR/NAME.stdout.log, -# closed to others and listed in LOGDIR/.licensed-logs. TMP_LOGDIR is -# the --tmp-logdir eb ran with; without it, the newest log in -# EasyBuild's default place is used, unless it is another build's. -# NAME.stdout.log and a TMP_LOGDIR below LOGDIR are closed to others too. -# eb-keep-logs rotate ROOT --compress-after DAYS [--delete-after DAYS] -# [--lock-timeout SECONDS] -# In the run directories directly under ROOT (named YYYYMMDD_HHMMSS), -# gzip the logs of runs older than DAYS; with --delete-after, remove -# whole runs older than that. Permissions and .licensed-logs follow. -# EB_KEEP_LOGS_NOW, in seconds since the epoch, sets the current time. -# One rotate at a time holds ROOT/.eb-keep-logs-rotate.lock; another -# waits up to SECONDS for it (600; 0 does not wait), then exits 75. -# eb-keep-logs --help | --version -# # A failed build's log is in EasyBuild's tmpdir on the build node, which goes # with the job; and EasyBuild wraps the "Results of the build can be found in # the log file(s)" line, so parsing stdout for the path finds nothing. @@ -28,7 +10,65 @@ set -uo pipefail VERSION=0.1.0 -usage() { sed -n '2,23p' "$0" | sed 's/^# \{0,1\}//'; } +# src/main.zig's usage_text holds the same text: tests/differential.sh +# compares the two. +usage() { + cat <<'EOF' +eb-keep-logs: keep the logs of EasyBuild builds that a build pipeline would +otherwise lose, and keep the pipeline's log tree bounded. + + eb-keep-logs failed STATUS NAME LOGDIR [TMP_LOGDIR] + After `eb` returned STATUS for easyconfig NAME: when STATUS is not 0, + copy the EasyBuild session log `eb --last-log` names, the failing + command's output and a meson testlog next to LOGDIR/NAME.stdout.log, + closed to others and listed in LOGDIR/.licensed-logs. TMP_LOGDIR is + the --tmp-logdir eb ran with; without it, the newest log in + EasyBuild's default place is used, unless it is another build's. + NAME.stdout.log and a TMP_LOGDIR below LOGDIR are closed to others too. + eb-keep-logs rotate ROOT --compress-after DAYS [--delete-after DAYS] + [--lock-timeout SECONDS] + In the run directories directly under ROOT (named YYYYMMDD_HHMMSS), + gzip the *.log and *.txt files of old runs and remove older runs + whole, leaving alone a run that is still written into. A run's age is + in days from the local midnight of the date in its name. Permissions + and .licensed-logs follow. One rotate of ROOT runs at a time, holding + ROOT/.eb-keep-logs-rotate.lock. Options and ROOT come in any order. + --compress-after DAYS, --compress-after=DAYS + Gzip the files of runs at least DAYS old. Required; there is no + default. + --delete-after DAYS, --delete-after=DAYS + Remove whole runs at least DAYS old; DAYS must be larger than + that of --compress-after. Default: none; no run is removed. An + empty value is the default. + --lock-timeout SECONDS, --lock-timeout=SECONDS + While another rotate holds the lock, wait up to SECONDS for it, + then give up and exit 75. Default: 600; 0 does not wait. An empty + value is the default. + eb-keep-logs -h | --help + Print this help on stdout and exit 0. + eb-keep-logs --version + Print the version line on stdout and exit 0. + +Environment: + PATH Where failed looks up eb. + EASYBUILD_TMPDIR failed copies a command's output only from below it; + unset or empty, it copies none. + EB_KEEP_LOGS_NOW The time rotate takes as now, in seconds since the + epoch; unset or empty, the current time. + EB_PIPELINE_LOG_DIR rotate leaves alone the run that holds this path. + TZ, TZDIR The time zone of the local midnights, and the + directory of zone files. + +Exit status: + 0 -h, --help or --version, or a failed or rotate that accepted its + arguments, whatever it could keep, compress or remove: what it could + not do is reported on stderr. + 2 The invocation was refused, with eb-keep-logs: MESSAGE on stderr; or + no command was given, and this help is on stdout. + 75 rotate waited --lock-timeout seconds for the lock another rotate + held, then gave up and changed nothing; run it again later. +EOF +} die() { echo "eb-keep-logs: $*" >&2; exit 2; } diff --git a/src/main.zig b/src/main.zig index c12865b..491d1e9 100644 --- a/src/main.zig +++ b/src/main.zig @@ -18,6 +18,8 @@ const tool = "eb-keep-logs"; /// build.zig.zon names the same one, and a release changes both. pub const version = "0.2.1"; +/// What `-h`, `--help` and no arguments print. The shell script's `usage` +/// prints the same text: tests/differential.sh compares the two. const usage_text = \\eb-keep-logs: keep the logs of EasyBuild builds that a build pipeline would \\otherwise lose, and keep the pipeline's log tree bounded. @@ -33,12 +35,45 @@ const usage_text = \\ eb-keep-logs rotate ROOT --compress-after DAYS [--delete-after DAYS] \\ [--lock-timeout SECONDS] \\ In the run directories directly under ROOT (named YYYYMMDD_HHMMSS), - \\ gzip the logs of runs older than DAYS; with --delete-after, remove - \\ whole runs older than that. Permissions and .licensed-logs follow. - \\ EB_KEEP_LOGS_NOW, in seconds since the epoch, sets the current time. - \\ One rotate at a time holds ROOT/.eb-keep-logs-rotate.lock; another - \\ waits up to SECONDS for it (600; 0 does not wait), then exits 75. - \\ eb-keep-logs --help | --version + \\ gzip the *.log and *.txt files of old runs and remove older runs + \\ whole, leaving alone a run that is still written into. A run's age is + \\ in days from the local midnight of the date in its name. Permissions + \\ and .licensed-logs follow. One rotate of ROOT runs at a time, holding + \\ ROOT/.eb-keep-logs-rotate.lock. Options and ROOT come in any order. + \\ --compress-after DAYS, --compress-after=DAYS + \\ Gzip the files of runs at least DAYS old. Required; there is no + \\ default. + \\ --delete-after DAYS, --delete-after=DAYS + \\ Remove whole runs at least DAYS old; DAYS must be larger than + \\ that of --compress-after. Default: none; no run is removed. An + \\ empty value is the default. + \\ --lock-timeout SECONDS, --lock-timeout=SECONDS + \\ While another rotate holds the lock, wait up to SECONDS for it, + \\ then give up and exit 75. Default: 600; 0 does not wait. An empty + \\ value is the default. + \\ eb-keep-logs -h | --help + \\ Print this help on stdout and exit 0. + \\ eb-keep-logs --version + \\ Print the version line on stdout and exit 0. + \\ + \\Environment: + \\ PATH Where failed looks up eb. + \\ EASYBUILD_TMPDIR failed copies a command's output only from below it; + \\ unset or empty, it copies none. + \\ EB_KEEP_LOGS_NOW The time rotate takes as now, in seconds since the + \\ epoch; unset or empty, the current time. + \\ EB_PIPELINE_LOG_DIR rotate leaves alone the run that holds this path. + \\ TZ, TZDIR The time zone of the local midnights, and the + \\ directory of zone files. + \\ + \\Exit status: + \\ 0 -h, --help or --version, or a failed or rotate that accepted its + \\ arguments, whatever it could keep, compress or remove: what it could + \\ not do is reported on stderr. + \\ 2 The invocation was refused, with eb-keep-logs: MESSAGE on stderr; or + \\ no command was given, and this help is on stdout. + \\ 75 rotate waited --lock-timeout seconds for the lock another rotate + \\ held, then gave up and changed nothing; run it again later. \\ ; @@ -924,6 +959,14 @@ test "parseSeconds" { try std.testing.expectEqual(max_lock_timeout, parseSeconds("123456789012345678901234567890")); } +test "usage_text gives the lock timeout's default and the exit statuses" { + const fmt = std.fmt.comptimePrint; + try std.testing.expect(std.mem.indexOf(u8, usage_text, fmt("Default: {d};", .{default_lock_timeout})) != null); + try std.testing.expect(std.mem.indexOf(u8, usage_text, fmt("give up and exit {d}.", .{lock_busy_exit})) != null); + try std.testing.expect(std.mem.indexOf(u8, usage_text, fmt("\n {d} The invocation was refused", .{cli.usage_exit})) != null); + try std.testing.expect(std.mem.indexOf(u8, usage_text, fmt("\n {d} rotate waited --lock-timeout", .{lock_busy_exit})) != null); +} + test "listed" { try std.testing.expect(listed("/l/a.log\n/l/b.log\n", "/l/b.log")); try std.testing.expect(listed("/l/a.log", "/l/a.log")); diff --git a/tests/differential.sh b/tests/differential.sh index d165af2..fdf54ac 100644 --- a/tests/differential.sh +++ b/tests/differential.sh @@ -16,8 +16,13 @@ chmod +x "${work}/bin/eb" export PATH="${work}/bin:${PATH}" diffs=0 -# Labels whose difference COMPAT.md documents. -deliberate=("no arguments" "rotate, lock is a symbolic link") +# Labels whose difference is deliberate, each with its case in COMPAT.md. A +# difference passes only while COMPAT.md lists that case among the +# deliberate differences. +declare -A deliberate=( + ["rotate, lock is a symbolic link"]="\`rotate\`'s lock file cannot be opened, or is a symbolic link or not a regular file" +) +compat_deliberate=$(sed -n '/^## Deliberate differences$/,/^## /p' "${repo_root}/COMPAT.md") # The environment both runs get, as env(1) takes it. run_env=(PATH="${PATH}") # compare LABEL ARGS...: run both with the same arguments. @@ -26,16 +31,15 @@ compare() { env "${run_env[@]}" "${OLD_BIN}" "$@" > "${work}/o.out" 2> "${work}/o.err"; local oc=$? env "${run_env[@]}" "${TOOL_BIN}" "$@" > "${work}/n.out" 2> "${work}/n.err"; local nc=$? if [ "${oc}" != "${nc}" ] || ! cmp -s "${work}/o.out" "${work}/n.out" || ! cmp -s "${work}/o.err" "${work}/n.err"; then - local d - for d in "${deliberate[@]}"; do - if [ "${d}" = "${label}" ]; then - echo "deliberate ${label}" - return - fi - done + local compat_case="${deliberate[${label}]:-}" + if [ -n "${compat_case}" ] && grep -qF -- "| ${compat_case} |" <<< "${compat_deliberate}"; then + echo "deliberate ${label}" + return + fi # On stderr: zig build test shows a script's stderr, not stdout. { echo "DIFF ${label}: exit ${oc} vs ${nc}" + [ -z "${compat_case}" ] || echo " COMPAT.md lists no deliberate difference: ${compat_case}" diff "${work}/o.out" "${work}/n.out" | sed 's/^/ out /' diff "${work}/o.err" "${work}/n.err" | sed 's/^/ err /' } >&2 @@ -46,6 +50,8 @@ compare() { } compare "no arguments" +compare "--help" --help +compare "-h" -h compare "unknown command" bogus compare "failed, too few" failed 1 Foo compare "failed, bad status" failed x Foo "${work}/logs" diff --git a/tests/test_eb_keep_logs.sh b/tests/test_eb_keep_logs.sh index 4ac67c4..787d1e5 100755 --- a/tests/test_eb_keep_logs.sh +++ b/tests/test_eb_keep_logs.sh @@ -341,6 +341,55 @@ check "rotate without --compress-after refused" "$?" "2" # --help: what `failed` copies, and the variable `rotate` reads check "help: the copy is the session log" "$("${tool}" --help | grep -c 'EasyBuild session log')" "1" check "help: EB_KEEP_LOGS_NOW" "$("${tool}" --help | grep -c 'EB_KEEP_LOGS_NOW')" "1" +# --help lists every option either parser takes: the words starting with - +# that the shell script's case patterns and the Zig build's comparisons of +# an argument name. An option that takes a value gives its default or says +# it is required, and the exit statuses are listed. +"${tool}" --help > "${work}/help" +options=$({ + grep -oE -- '^ *-[-a-z|=*]+\)' "${repo_root}/eb-keep-logs" | tr -d ' )*' | tr '|' '\n' | grep -vx -- - + grep -oE '\(u8, [a-z_]+, "-[^"]*"\)' "${repo_root}/src/main.zig" | cut -d '"' -f 2 +} | LC_ALL=C sort -u) +# listed OPT: whether --help names OPT as a word, or OPT= followed by a value. +listed() { + case "$1" in + *=) grep -qE -- "(^|[[ ,|])$1[A-Z]" "${work}/help" ;; + *) grep -qE -- "(^|[[ ,|])$1(\$|[] ,|])" "${work}/help" ;; + esac +} +# entry OPT: the line of --help that starts with OPT and the lines indented +# under it. +entry() { + awk -v opt="$1 " ' + { match($0, /^ */) } + found && RLENGTH <= depth { exit } + found { print } + !found && substr($0, RLENGTH + 1, length(opt)) == opt { found = 1; depth = RLENGTH; print } + ' "${work}/help" +} +check "help: lists every option" "$(for opt in ${options}; do listed "${opt}" || echo "${opt}"; done)" "" +check "help: each option with a value gives its default" \ + "$(for opt in ${options}; do [[ "${opt}" != *= ]] || [ "$(entry "${opt%=}" | grep -cE 'Default: |Required')" = 1 ] || echo "${opt%=}"; done)" "" +check "help: --lock-timeout waits 600 s by default" "$(entry --lock-timeout | grep -c 'Default: 600;')" "1" +check "help: exit statuses" "$(sed -n '/^Exit status:$/,$p' "${work}/help" | grep -oE '^ [0-9]+ ' | tr -d ' ' | tr '\n' ' ')" "0 2 75 " +# whole: the last line of each paragraph that does not end with a full stop, +# then the first two words of the last paragraph. What --help, -h and no +# arguments print is whole when that is only "Exit status:". +whole() { awk -v RS= '{ n = split($0, line, "\n"); if (line[n] !~ /\.$/) print line[n]; last = $1 " " $2 } END { print last }'; } +check "help: --help prints it whole" "$(whole < "${work}/help")" "Exit status:" +check "help: -h prints it whole" "$("${tool}" -h | whole)" "Exit status:" +"${tool}" > "${work}/usage" +check "help: no arguments print it whole, with exit 2" "$?: $(whole < "${work}/usage")" "2: Exit status:" +# eb-pipeline passes --lock-timeout where `--help` exits 0 and names it. +check "help: as eb-pipeline reads it" "$("${tool}" --help | grep -c -- --lock-timeout > /dev/null; echo "${PIPESTATUS[*]}")" "0 0" +# The example under "*** --help" in the cli reference is the usage as printed. +reference_help=$(awk ' + /^\*\*\* / { in_help = ($0 == "*** --help") } + in_help && /^#\+end_example$/ { exit } + shown { print } + in_help && /^#\+begin_example$/ { shown = 1 } +' "${repo_root}/docs/orgmode/reference/cli.org") +check "help: as the cli reference shows it" "$(diff <(printf '%s\n' "${reference_help}") "${work}/help")" "" # rotate: the run rotate writes into is still going and is left alone. A run # that started before midnight is a day old just after it. next_day=$(date -d '2026-11-14 00:10' +%s)