From 41b4de0b155475031cbafc13fe92a56b9014b2de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Rapha=C3=ABl=20Vig=C3=A9e?= Date: Tue, 4 Aug 2026 17:10:26 +0200 Subject: [PATCH] docs: heph run fails when the selector matches nothing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit heph/hephbuild#351 changed `heph run` to exit non-zero when its selector (label, package matcher, or -e expression) matches no targets, instead of silently building nothing and exiting 0. `heph query` is unaffected — an empty result there is still valid. Document the new behavior in the CI guide (where a silently-passing empty run is most dangerous) and next to the -e/--expr reference. --- website/docs/guides/ci.md | 15 +++++++++++++++ website/docs/plugins/query.md | 6 ++++++ 2 files changed, 21 insertions(+) diff --git a/website/docs/guides/ci.md b/website/docs/guides/ci.md index 1964c22..02cc396 100644 --- a/website/docs/guides/ci.md +++ b/website/docs/guides/ci.md @@ -28,6 +28,21 @@ If a generated file is missing or out of date, the run exits non-zero with a diff — so a contributor who forgot to regenerate gets a red build, not a silent drift. +## Selectors that match nothing fail the run + +`heph run` exits non-zero if its selector matches no targets. A typo'd label, +an unbuilt variant, or a package matcher outside the workspace used to build +nothing and exit 0 — indistinguishable from a job that legitimately had +nothing to do. Now it fails loud instead. Debug a selector that isn't +matching what you expect with: + +```bash title="terminal" +heph query -e '' +``` + +This only applies to `heph run`. A `heph query` that matches nothing is a +legitimate answer. + ## Validate the workspace [`heph validate`](/docs/guides/validate) checks that every target resolves, that diff --git a/website/docs/plugins/query.md b/website/docs/plugins/query.md index 8e6ddf0..a5c7357 100644 --- a/website/docs/plugins/query.md +++ b/website/docs/plugins/query.md @@ -113,6 +113,12 @@ The old `-e`/`--exclude` flag was removed. Use `!` inside a query expression to exclude targets — for example `//... && !//vendor/...`. ::: +:::note +`heph run` fails if a selector — whether a label, a package matcher, or a +`-e` expression — matches no targets, instead of silently building nothing. +`heph query` has no such check: an empty result is a valid answer. +::: + ## `query()` in BUILD files The `query()` builtin lets a BUILD file select targets dynamically, the same