From 7d391315d3ee696862d602f204d963791eaebbba Mon Sep 17 00:00:00 2001 From: Rohit Goswami Date: Tue, 17 Nov 2026 02:52:02 +0000 Subject: [PATCH 1/2] fix(help): print the whole usage, with each option and its default The shell script printed lines 2 to 23 of itself as its usage: a range moved by hand each time the usage grew, and two lines too long in every version, so --help, -h and no arguments ended with a blank line and half a sentence of the comment after the usage. The Zig build's usage stopped before those lines, and COMPAT.md listed the difference as deliberate. Neither named -h or the --OPTION=VALUE forms, said that --compress-after is required or that --delete-after has no default, or gave an exit status but 75, and the default of --lock-timeout was in a sentence about the lock. Both said that rotate takes the runs older than DAYS, where it takes the runs at least DAYS old. The shell script's usage is now a quoted here-document, and the Zig build's usage_text holds the same text: each command, each of rotate's options in both forms with what it does and its default, the environment variables, and the exit statuses 0, 2 and 75, last. COMPAT.md lists the usage as kept. The suite reads the options from both parsers, the shell script's case patterns and the Zig build's comparisons of an argument, and checks that --help lists each of them, that each option that takes a value gives its default or says it is required, that --lock-timeout waits 600 seconds by default, and that the exit statuses are 0, 2 and 75. It checks that --help, -h and no arguments print the usage whole, with every paragraph ending in a full stop and the exit statuses last, and that --help exits 0 and names --lock-timeout, as eb-pipeline reads it. The differential run compares --help and -h, and passes a difference only while COMPAT.md lists its case among the deliberate differences. A unit test checks that usage_text gives default_lock_timeout, lock_busy_exit and cli.usage_exit. --- COMPAT.md | 2 +- changelog.d/+help-text.bugfix.md | 1 + eb-keep-logs | 78 ++++++++++++++++++++++++-------- src/main.zig | 55 +++++++++++++++++++--- tests/differential.sh | 24 ++++++---- tests/test_eb_keep_logs.sh | 41 +++++++++++++++++ 6 files changed, 166 insertions(+), 35 deletions(-) create mode 100644 changelog.d/+help-text.bugfix.md 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/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/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..857dd2e 100755 --- a/tests/test_eb_keep_logs.sh +++ b/tests/test_eb_keep_logs.sh @@ -341,6 +341,47 @@ 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" # 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) From 8935ba10d63b6adf841951585fd91a35736d2b52 Mon Sep 17 00:00:00 2001 From: Rohit Goswami Date: Tue, 17 Nov 2026 02:52:36 +0000 Subject: [PATCH 2/2] docs(cli): show the usage as --help prints it The reference's synopsis and its exit status 0 named --help but not -h. They name both now, and the reference shows the usage under --help, as it shows the version line under --version. The suite checks that the example there is what --help prints, so a change to the usage that misses the reference fails. README.md said that rotate compresses and removes the runs older than DAYS. It says at least DAYS old, as the usage, the reference and the how-to do. --- README.md | 4 +- changelog.d/+help-reference.doc.md | 1 + docs/orgmode/reference/cli.org | 65 +++++++++++++++++++++++++++++- tests/test_eb_keep_logs.sh | 8 ++++ 4 files changed, 74 insertions(+), 4 deletions(-) create mode 100644 changelog.d/+help-reference.doc.md 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/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/tests/test_eb_keep_logs.sh b/tests/test_eb_keep_logs.sh index 857dd2e..787d1e5 100755 --- a/tests/test_eb_keep_logs.sh +++ b/tests/test_eb_keep_logs.sh @@ -382,6 +382,14 @@ check "help: -h prints it whole" "$("${tool}" -h | whole)" "Exit status:" 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)