Resolution & Precedence¶

This page defines which input dotenv-fusion selects and which value wins when the same name is available from several places.

Input file selection¶

Without -f/--file, load, check, and exec select the first existing file in this order:

1. .env-fuse
2. .env-fuse.local
3. .env

--load-order and DOTENV_FUSION_LOAD_ORDER promote named inputs while retaining the others. For example, --load-order=env expands to env,fuse,fuse-local. An explicit --file bypasses automatic selection.

--walk searches one parent directory when no local input exists. --walk-up N sets the maximum number of parents to search.

Variable lookup during resolution¶

References such as ${NAME} use the first available source:

1. Compilation variables passed with --var NAME=value
2. Values already parsed from the main file and its imports
3. The parent process environment
4. The default in ${NAME:-default}

An unresolved reference becomes an empty string in normal mode. Strict mode reports it as an error. During fuse, explicitly lazy definitions can remain as references in the generated artifact.

Definitions inside files¶

Definitions are first-wins by default:

PORT=8000
#@import local.env

If local.env also defines PORT, the value remains 8000. Allow later values to replace earlier ones for one import:

#@import local.env override=true

Or change processing mode for subsequent definitions:

#@mode override=true
PORT=9000
#@mode override=false

An import can also add a prefix, so imported names do not compete with names in the parent file:

#@import database.env prefix=DB_

Parent environment versus resolved values¶

load and exec replace matching variables in the destination environment by default. Use --no-override to preserve parent values. The same choice applies to shell exports emitted by fuse --load.

dotenv-fusion exec --no-override -- application
eval "$(dotenv-fusion load --no-override)"

DOTENV_FUSION_EXISTING_ENV accepts override or no-override. An explicit CLI option takes priority over that setting.

For a source-backed variable, --no-override also avoids contacting the backend when the parent environment already supplies the value.

Quotes and expansion¶

See Syntax & Directives for the complete syntax and CLI Commands for command-specific options.