Documentation
¶
Overview ¶
Package dotenv parses .env files into a map and (optionally) applies them to the process environment. Designed for the framework's startup path so apps get familiar .env behavior without taking on a third-party dependency.
Format (a strict subset of the de facto dotenv spec):
# comments and blank lines are allowed
FOO=bar # bareword value
QUOTED="hello world" # double-quoted: escapes interpreted
LITERAL='hello\nworld' # single-quoted: VERBATIM, no escapes
export PORT=8080 # optional `export` prefix tolerated
PATH_TPL="${HOME}/bin" # ${VAR} expansion (double-quoted only)
Hard rules:
- Keys must start with a letter or underscore; rest is [A-Za-z0-9_].
- Multi-line values are NOT supported. Use \n inside a double-quoted value if you need a newline character.
- Inline comments after an UNQUOTED value are preserved as part of the value. Write a quoted value if you need to embed `#`.
- On a malformed line the parser returns an error with line number.
See Expand for the variable-expansion semantics (values substitute verbatim, undefined-as-empty, \$ escape).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Apply ¶
Apply writes vals into the process environment via os.Setenv, but ONLY for keys not already present in os.Environ. Returns the keys actually set (loaded) and those skipped because env already had a value. Both slices are sorted for stable test output.
Existing env wins. Operators expect their explicit configuration to override dotfiles. (Some loaders flip this; do not.)
func Expand ¶
Expand performs ${VAR} substitution in s, drawing values from local first then envFn. Bracket form ONLY. Bare $VAR is left verbatim (less ambiguous, fewer footguns).
Rules:
- A looked-up value goes in verbatim, the way a shell substitutes a variable: it is never expanded again. Parse stores each value already resolved, so re-expanding it would turn a single-quoted literal or an escaped `\$` back into a lookup; an environment value holding `${x}` is data, not a template. A self-reference (`A=${A}`) therefore yields A's stored text, and no cycle can form.
- Undefined names → empty string (consistent with shell behavior).
- `\$` is an escape: it emits a literal `$` that starts no lookup.
- Malformed `${...` without closing `}` is left verbatim, better than silently dropping bytes.
envFn may be nil. In that case the only lookup source is local.
func Load ¶
Load reads one or more .env files and returns the merged key/value map. EARLIER paths take precedence on key conflict, and a ${NAME} in a double-quoted value reads the value that ends up applied: os.Environ first (Apply never overwrites it), then an earlier file's value, then the same file's earlier keys, then empty. With DB_HOST=prod in the environment, DATABASE_URL="postgres://${DB_HOST}/app" is built on prod, and a later file's ${DB_HOST} matches the DB_HOST that is applied, not the one an earlier file shadowed. The convention is to pass most-specific first (e.g. .env.local, .env.<APP_ENV>, .env). Missing files are silently skipped; a malformed file returns an error naming the file.
func LoadAndApply ¶
LoadAndApply is Load + Apply in one call, the common shape for boot-time wiring.
func Parse ¶
Parse reads .env content from r and returns the parsed key/value map. Variable expansion is performed on double-quoted values using already-parsed keys (later lines see earlier lines) and nothing else: Parse reads no environment. Load adds the earlier files and the os.Environ fallback; Expand takes a custom lookup.
Duplicate keys: last wins.
Types ¶
This section is empty.
Source Files