Skip to content

About the config cascade

CONGA validates config files into the config source of the value precedence order. Scalar and slice values flatten to strings, and map flags keep their per-key pairs with the contributing file recorded as their origin. Formats are opt-in packages, and only registered formats are linked into the application binary. The practical steps — registering decoders, declaring search paths, and cascading — live in How to manage config files.

By default the search paths are first-hit. conga.ConfigPaths(...) lists files in precedence order and the first existing one wins. Declaring conga.ConfigCascading() changes the model to a merge, in which every existing file contributes, from lowest to highest precedence. Partial cascades are supported, so any subset of the list may exist.

Merge semantics differ by value shape. Scalar and slice flags take the nearest file’s value. A later file replaces what an earlier file set. Map flags (map[K]V fields and conga.Features[T] gates) merge key by key across the files. Files apply in lowest-to-highest precedence, a later file overrides only the keys it names, and keys set only by an earlier file survive. The --why report attributes each merged map key to the file that last wrote it.

Because a cascade can load more than one file, a declared root config-file flag must accept multiple values (multi:"true") so it can report every merged file. The schema rejects the combination otherwise.

conga.ConfigExplicit(...) specifies a single configuration file target, the application’s default file. A missing file is an error, and a file the user names with --config-file or <PREFIX>_CONFIG replaces it. It cannot be combined with conga.ConfigPaths(...) or conga.ConfigCascading(). Attempting to combine them fails schema initialization with ErrSchema and is reported as a violation by conga-lint.

A conga.Bootstrapper supplies a configuration document from code with Bootstrap.SetConfig. The hook runs after the bootstrap pass binds fields tagged bootstrap:"true" on the selected command chain and before file resolution, so it can select a config file from a flag and still contribute a document. The document is the highest-precedence contributor within the config source. It overlays the file-resolved values key by key, winning the keys it names while file keys it does not name survive. CONGA validates the document through the same pipeline as a decoded file. Loaded values keep the config source’s rank, map flags merge key by key, and --why attributes each value to the free-form origin label the application recorded with Set, as it attributes a file’s values to the file path.

A programmatic document records origins using Set, SetScoped, SetKey, and SetKeyScoped. When a document layers multiple files or profiles, SetKey merges map flags key by key so subsequent layers override only the specific keys they name. When an entry originates from a sub-section of a file (such as a named pipeline or profile), SetScoped records an optional scope (origin › scope). The --why report renders the scoped origin in value attribution, while CandidateConfigFiles and LoadedConfigFiles report the origin path once without duplicating entries.

Because SetConfig only adds to the config source, a Bootstrapper works alongside conga.ConfigPaths, conga.ConfigExplicit, conga.ConfigCascading, app.RegisterDecoder, and a root ConfigFile field. An application that only loads .env files implements Bootstrap without calling SetConfig. Errors returned from Bootstrap classify under ErrConfig (exit 1, app-authored data). See How to load domain documents and the runnable 30 — Bootstrapping flag-selected files example.

Config file resolution lists the search order and the result of each failure.

A path the user names is one they expect to be read, so a missing file is an error. A search path is only a place to look, so a missing file there is skipped. kubectl --kubeconfig, curl --config, and ssh -F fail on a missing named file in the same way, while a search list such as KUBECONFIG skips missing entries. Paths the user names outrank paths the program sets. The --config-file flag comes first, then the environment variable, then ConfigExplicit, then the search paths.

When the app is config-capable (at least one registered decoder and a resolvable name) and declares no search paths, CONGA probes:

${XDG_CONFIG_HOME:-~/.config}/<app-name>/config.<ext>
${XDG_CONFIG_HOME:-~/.config}/<app-name>/<app-name>.<ext>

for each registered extension, and falls back to <app-name>.<ext> beside the directory when it doesn’t exist (Config file resolution gives the probing rule for every search path). This is the lowest-precedence search path and is replaced entirely by conga.ConfigPaths(...). A ConfigFile container loads a file only when an invocation names it explicitly (the ConfigFile flag, the config environment variable, or conga.ConfigExplicit(...)) or a search path discovers it. About value precedence explains why the container sits outside the precedence order. The --why report and session.CandidateConfigFiles() list the candidates an invocation evaluates.

Resolution reads only formats the application registered. Search paths probe only registered extensions, and no wire-format library is linked unless a decoder package is. A decoderless application still records candidate paths. The config-file flag’s help text ends with (no configuration decoder registered), and session.CandidateConfigFiles() reports the environment targets. A named target whose format has no decoder is fatal. The missing-decoder rule and registration mechanics are cataloged in package decoder. A decoderless app leaves the config source inactive, as described in About value precedence.