From 59f2ee851793d251ab37415e60c1445e8dabc745 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Vig=C3=A9e?= Date: Sun, 21 Jun 2026 12:21:59 +0100 Subject: [PATCH 1/2] docs: document --log-lines flag and real log line numbers in failure box --- website/docs/guides/inspecting-builds.md | 32 ++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/website/docs/guides/inspecting-builds.md b/website/docs/guides/inspecting-builds.md index 56831ae..be87a95 100644 --- a/website/docs/guides/inspecting-builds.md +++ b/website/docs/guides/inspecting-builds.md @@ -64,6 +64,38 @@ Useful when a provider adds its own callable beyond the core [builtins](/docs/plugins/buildfile#authoring-build-files), or to check argument names and types before writing a call. +## Reading failure output + +When a target fails, heph prints a diagnostic box with the trailing lines of its +process log: + +``` +× target failed: //app:server +╰─▶ exit status: 1 + ╭─[log] + 91 │ connecting to db... + 92 │ FATAL: connection refused + ╰──── +``` + +Line numbers reflect the real position in the full log — the last 10 lines of a +100-line log are numbered 91–100, not 1–10. + +By default, `heph run` shows 10 trailing lines. Use `--log-lines` to show more +or fewer: + +```bash title="terminal" +heph run //app:server --log-lines 50 +``` + +The full log is always saved as the `log.txt` artifact regardless of `--log-lines`. +To read it directly: + +```bash title="terminal" +heph run //app:server --log-lines 0 # suppress the inline tail +heph run //app:server --cat-out # print log.txt to stdout after the run +``` + ## Reproducing the environment To go past inspection and actually poke at a failing target, open its From 7ab46792d14770e26a055be170cb8d2e2af3efad Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Vig=C3=A9e?= Date: Sun, 21 Jun 2026 12:23:34 +0100 Subject: [PATCH 2/2] docs: fix log.txt access instructions in failure output section --- website/docs/guides/inspecting-builds.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/website/docs/guides/inspecting-builds.md b/website/docs/guides/inspecting-builds.md index be87a95..aa10fdd 100644 --- a/website/docs/guides/inspecting-builds.md +++ b/website/docs/guides/inspecting-builds.md @@ -81,19 +81,20 @@ process log: Line numbers reflect the real position in the full log — the last 10 lines of a 100-line log are numbered 91–100, not 1–10. -By default, `heph run` shows 10 trailing lines. Use `--log-lines` to show more -or fewer: +By default, `heph run` shows 10 trailing lines. Use `--log-lines` to see more: ```bash title="terminal" heph run //app:server --log-lines 50 ``` -The full log is always saved as the `log.txt` artifact regardless of `--log-lines`. -To read it directly: +The full log is always written to `log.txt` inside the target's sandbox. A +failed target's sandbox is preserved until its next run, so you can read the +complete log by opening the sandbox: ```bash title="terminal" -heph run //app:server --log-lines 0 # suppress the inline tail -heph run //app:server --cat-out # print log.txt to stdout after the run +heph run //app:server --shell +# then inside the shell: +cat log.txt ``` ## Reproducing the environment