Skip to content

docs(configuration): an empty entry in the --env file sets an empty value, not the default #1217

Description

@Chemaclass

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

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type

Projects

Status
Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions