Dotenv files
app.Dotenv(paths...) enables zero-dependency .env loading. Loaded variables populate the process environment before flag resolution, feeding the environment source of the value precedence order. The task-oriented setup is in How to load .env files.
Loading rules
Section titled “Loading rules”func (a *App[T]) Dotenv(paths ...string) *App[T]| Call | Files | Missing file | Key conflicts |
|---|---|---|---|
Dotenv() |
.env, then .env.local, in the working directory |
Silently ignored | The last definition wins; the process environment outranks both files |
Dotenv(path1, path2, ...) |
Each named path, in order | Fatal error wrapping conga.ErrConfig |
The last definition wins; the process environment outranks files |
app.Dotenv() loads non-destructively, so process environment variables take precedence over file values, preserving shell, container, and CI configurations. Files apply in order, so .env.local overrides keys defined in .env, and each named path overrides preceding paths.
Loaded variables are written into the process environment through os.Setenv. app.SetenvFunc replaces that writer. Tests pass testing.T.Setenv (.SetenvFunc(t.Setenv)) so loaded values revert automatically when the test finishes.
Bootstrap-phase loading
Section titled “Bootstrap-phase loading”A conga.Bootstrapper loads .env files whose paths derive from bootstrap-tagged flags with Bootstrap.Dotenv(paths...). It runs after bootstrap-field binding and before configuration resolution, so a path such as filepath.Join(c.Dir.Get(), ".env") is available. Bootstrap.Dotenv tolerates missing files, while Bootstrap.DotenvExplicit fails with conga.ErrConfig when a named file is absent, matching Dotenv(path1, path2, ...). An argument-less Bootstrap.Dotenv() probes .env and then .env.local in the working directory, matching app.Dotenv().
Both phases share one origin map. Variables already present in the host process environment are never overwritten, and a file loaded by Bootstrap.Dotenv overrides a key an earlier app.Dotenv file set. --why attributes an env-sourced value to its .env file (for example env (sub/.env)), while host variables render as bare env.
Completion invocations (__complete) run Bootstrap before resolving candidates, so values from the environment, feature gates included, shape suggestions as they do in a real run. A loading failure doesn’t stop completion. The real run reports it as a normal error.
Grammar
Section titled “Grammar”| Feature | Behavior |
|---|---|
| Comments | Lines whose first non-space character is # are ignored; unquoted values drop a trailing # comment after whitespace. |
export prefix |
export PORT=8080 is parsed identically to PORT=8080. |
| Unquoted values | Taken as written after inline-comment stripping, with variable references expanded. A backslash is kept, so \$ doesn’t stop expansion, and A=cost\$HOME gives cost\ followed by the value of HOME. Use single quotes, or \$ inside double quotes, to write a literal $. |
| Single quotes | Literal; escapes remain uninterpreted. A single-quoted value can’t contain '. Use double quotes and \" instead. |
| Double quotes | The escapes \n, \r, \t, \", \\, and \$ are evaluated, and \$ is a literal $ that never starts a variable reference. Only whitespace or a comment may follow the closing quote. |
| Multi-line values | A single- or double-quoted value may span lines and keeps the line breaks. The closing quote may be on the file’s last line. Inside double quotes, \n also writes a line break. |
| Variable expansion | $VAR and ${VAR} resolve from the process environment first, then from keys defined earlier in the file; a file overriding a key from an earlier file in the same call uses its own value. |
BASE_DIR=/var/dataLOG_DIR=${BASE_DIR}/logsPATH=${PATH}:/opt/binSize limit
Section titled “Size limit”.env files are capped at 16 MiB. A larger file is rejected with an error wrapping conga.ErrConfig, which bounds the memory a hostile file can claim.