Expansion is how ${VAR} references become values. You choose three things: which read call, which operator in the file, and which options (escape dialect, environment fallback, command substitution).
On this page: Which read call · Which operator · Which options · If X, use Y · Pitfalls · Related
| Call | Returns | On a failing ${VAR:?…} |
Use for | Guide | Example |
|---|---|---|---|---|---|
f.Get(key) |
the raw value, references intact | never fails | anything you write back | expansion, step 1 | ExampleFile_Get |
f.GetExpanded(key) |
one value, resolved; (value, found, err) |
returns a *RequiredError |
reading one value the way a consumer sees it | expansion, step 1 | ExampleFile_GetExpanded |
f.ExpandedMap() |
every active key, resolved | stops at the first error, returns no map | handing the whole configuration to a binder | expansion, step 7 | ExampleFile_ExpandedMap |
dotenv.Read(path) |
Open + ExpandedMap |
same as ExpandedMap |
a program that only consumes configuration | reading, step 1 | ExampleRead |
All operators are Docker Compose's. "Empty" means set to "".
| You want | Write | Unset | Empty | Set to x |
Example |
|---|---|---|---|---|---|
| the value | ${VAR} or $VAR |
"" |
"" |
x |
ExampleFile_GetExpanded |
| a default when it is missing or empty | ${VAR:-d} |
d |
d |
x |
ExampleFile_GetExpanded_operators |
| a default only when it is missing | ${VAR-d} |
d |
"" |
x |
same |
| an alternative when it has a value | ${VAR:+alt} |
"" |
"" |
alt |
same |
| an alternative when it is set at all | ${VAR+alt} |
"" |
alt |
alt |
same |
| to fail loudly when missing or empty | ${VAR:?msg} |
error | error | x |
ExampleRequiredError |
| to fail loudly only when missing | ${VAR?msg} |
error | "" |
x |
same |
a literal $ |
$$ |
— | — | — | ExampleFile_GetExpanded_dollar |
| no expansion at all for this value | single quotes or backticks: '${VAR}' |
— | — | — | ExampleFile_GetExpanded_literal |
Operators nest: ${A:-${B:-c}} works, and so do chains (C=${B} where B=${A}) (ExampleFile_GetExpanded_nesting).
| Option | Default | Turn it on when | Guide | Example |
|---|---|---|---|---|
WithEscapes(EscapeExtended) |
on | your files use \n, \t, \r inside double quotes as escapes |
syntax, step 9 | ExampleWithEscapes |
WithEscapes(EscapeCompose) |
off | Docker Compose reads the same file, or values hold Windows paths or regexes where \n must stay two characters |
syntax, step 9 | ExampleEscapeCompose |
WithLookup(fn) |
off | references the file does not define should come from somewhere else, such as os.LookupEnv; the file always wins |
plugins, step 1 | ExampleWithLookup |
WithCommandSubstitution(true) |
off | you trust the file and want $(command) to run through sh -c |
expansion, step 9 | ExampleWithCommandSubstitution_order |
WithCommandRunner(fn) |
off | you want $(command) but only through your own runner (an allow-list, a sandbox, a fake in tests); installing it turns substitution on |
expansion, step 9 | ExampleWithCommandRunner_allowList |
- If you write the value back to a file, use
Get.GetExpandedoutput saved to disk flattens the reference for good. - If a value must be present for the program to work, write
${VAR:?message}in the file, and match the error witherrors.As(err, &re)wherereis a*dotenv.RequiredError. The two?forms are the only operators that produce an error. - If a value may legitimately be empty, use the forms without a colon (
-,+,?); the colon forms treat empty like unset. - If the file comes from somewhere you do not control (a repository, an image, a teammate), keep command substitution off. With it on, reading the file runs shell commands.
- If you need
$(command)in tests, useWithCommandRunnerwith a fake runner, never the real shell (ExampleWithCommandRunner). - If Docker Compose reads the same file, use
EscapeCompose; see Options for your kind of app.
- A failing command expands to
""with no error, as a shell does inside a value. A command that must succeed needs a check in your runner. WithCommandRunner(nil)turns on the realsh -c, the same asWithCommandSubstitution(true).- A key that refers to itself sees the line above it, as in Docker Compose.
A=1followed byA=${A}2gives12;ZONE=${ZONE:-x}with no earlierZONEasks your Lookuper, then givesx(ExampleFile_GetExpanded_selfReference). In library v0.1.1 and earlier these gave22and"". - Cycles terminate but can leave text. A reference that re-enters a variable already being expanded sees only the lines above, then the Lookuper, else
""; the rest of each value stays, soA=a${B}withB=b${A}givesA=ab(ExampleFile_GetExpanded_nesting). - Forward references differ from Compose. A reference to a key defined further down resolves here; Compose reads top to bottom and leaves it unset.
- Names stop at characters that are not part of a bare name.
$spring.urlreads$springfollowed by.url; use${spring.url}.${MY-KEY}reads as the-operator onMY(ExampleFile_GetExpanded_names). - A backslash never escapes a
$. Use$$.