.env.example cannot document a variable without making it an override

[Chemaclass]

src/env.sh loads .env with set -o allexport; source .env, so every line in it is an unconditional assignment. Adding a variable to .env.example purely as documentation therefore breaks that variable's env-var form as soon as anyone copies the file:

# with BASHUNIT_OUTPUT_FORMAT= present in .env
BASHUNIT_OUTPUT_FORMAT=tap ./bashunit tests/   # silently ignored

CI hits this directly — tests.yml has a Setup Config step that runs cp .env.example .env. This caused 12 red jobs on #862 and was invisible locally, because a developer's existing .env predates any newly added key.

.bashunitrc does not have the problem: bashunit::env::load_config_file applies each key with ${key:-val}, i.e. only when unset.

The bind is that .env.example is currently both the starter config and the reference documentation, and those two roles now conflict. Options:

1. Load .env with the same apply-when-unset semantics as .bashunitrc (changes precedence — needs a decision on whether .env should beat an exported variable).
2. Keep .env.example minimal and move the full variable reference to docs/configuration.md.
3. Ship the reference entries commented out.

A stopgap comment was added in #862 warning not to add variables there, but the underlying conflict stands.

[Chemaclass]

Confirmed live against a documented variable, which makes this more than theoretical.

BASHUNIT_DEV_LOG is listed in .env.example (line 58, empty). With that copied to .env, exporting it on the command line does nothing:

$ BASHUNIT_DEV_LOG="/tmp/fresh.log" bashunit --no-parallel log_test.sh
$ cat /tmp/fresh.log
cat: /tmp/fresh.log: No such file or directory      # never created

$ BASHUNIT_DEV_LOG="/tmp/fresh.log" bashunit --skip-env-file --no-parallel log_test.sh
$ cat /tmp/fresh.log
2026-07-25 09:52:40 [INFO]: I am tracing something... #log_test.sh:4

So the only way to use the env-var form of any variable listed in .env.example is --skip-env-file, which also discards every other setting. Worth noting when picking between the three options above — option 1 (apply-when-unset, matching .bashunitrc) is the only one that fixes this for the 37 variables already in the file, not just for ones we might add later.

[Chemaclass]

Reproduced this by accident while checking the quickstart's sample output, so recording it here as concrete evidence.

The repo's own .env (copied from .env.example) contains at line 22:

BASHUNIT_SHOW_EXECUTION_TIME=       # Default: true

An empty value. Because .env is loaded with set -o allexport; source .env, that line is an unconditional assignment, so it overrides a value the caller exported:

$ cd <repo>
$ BASHUNIT_SHOW_EXECUTION_TIME=true ./bashunit /tmp/qs/
✓ Passed: Bashunit is working                       # no per-test duration

$ cd /tmp/qs
$ BASHUNIT_SHOW_EXECUTION_TIME=true <repo>/bashunit .
✓ Passed: Bashunit is working                7ms    # works outside the repo

Same command, same flag, different result depending on whether a .env happens to list the variable. Nothing warns that the export was discarded.

This is exactly the failure mode the issue describes, and it is currently hitting bashunit's own checkout.