Problem
docs/configuration.md (Config file section) says:
Unlike .env, an empty entry in that file does wipe a value.
"Wipe" reads as "clear it back to the built-in default". It does not do that — it assigns the empty string, and for the many boolean settings an empty string is simply not true, so the observable result is false.
Measured with BASHUNIT_SHOW_HEADER (default true), ambient value true, custom.env containing BASHUNIT_SHOW_HEADER=:
| file |
ambient |
result |
--env custom.env |
true |
header hidden |
.env |
true |
header shown (preserved, as documented) |
If "wipe" meant the default, the first row would show the header. It hides it: the empty string wins and [ "$BASHUNIT_SHOW_HEADER" = "true" ] is false.
Cause
.env gets an explicit preservation pass in src/config/env.sh — non-empty BASHUNIT_* values are snapshotted and put back if the file blanked them. The --env/--boot path in src/main/test.sh is a plain source under allexport with no such pass, so KEY= is an unconditional assignment of empty.
Why it matters
A user blanking an entry in their --env file to "get the default back" silently gets a disabled boolean instead. Nothing reports it.
Suggested fix
Say what actually happens: an empty entry in the --env file overrides with an empty value rather than being ignored, and an empty value is not the default. Remove the entry to fall back to the default.
Verified correct in the same section
The rest of the documented precedence ladder was executed and every level holds:
- built-in default →
.bashunitrc → ambient environment → .env with a value → --env file
- an empty
.env entry preserves the ambient value
--env beats both .env and the ambient environment
--skip-env-file skips .env and .bashunitrc
- flag ordering:
--simple --env custom.env uses the file's value, --env custom.env --simple uses the flag
Problem
docs/configuration.md(Config file section) says:"Wipe" reads as "clear it back to the built-in default". It does not do that — it assigns the empty string, and for the many boolean settings an empty string is simply not
true, so the observable result isfalse.Measured with
BASHUNIT_SHOW_HEADER(defaulttrue), ambient valuetrue,custom.envcontainingBASHUNIT_SHOW_HEADER=:--env custom.envtrue.envtrueIf "wipe" meant the default, the first row would show the header. It hides it: the empty string wins and
[ "$BASHUNIT_SHOW_HEADER" = "true" ]is false.Cause
.envgets an explicit preservation pass insrc/config/env.sh— non-emptyBASHUNIT_*values are snapshotted and put back if the file blanked them. The--env/--bootpath insrc/main/test.shis a plainsourceunderallexportwith no such pass, soKEY=is an unconditional assignment of empty.Why it matters
A user blanking an entry in their
--envfile to "get the default back" silently gets a disabled boolean instead. Nothing reports it.Suggested fix
Say what actually happens: an empty entry in the
--envfile overrides with an empty value rather than being ignored, and an empty value is not the default. Remove the entry to fall back to the default.Verified correct in the same section
The rest of the documented precedence ladder was executed and every level holds:
.bashunitrc→ ambient environment →.envwith a value →--envfile.enventry preserves the ambient value--envbeats both.envand the ambient environment--skip-env-fileskips.envand.bashunitrc--simple --env custom.envuses the file's value,--env custom.env --simpleuses the flag