Getting started with ConfigStack

Most applications can use one DotCfg and one config file. Sometimes, though, your settings come from more than one file and some of those settings should override others.ConfigStack is for that case.

When one config file is not enough

Imagine an application with a file containing its normal defaults. A project using the application wants a different port, but it should not have to copy every default setting just to change one value.

The defaults file contains:

[server]
host = "127.0.0.1"
port = 3000

The project file only changes the port:

[server]
port = 8080

What the application needs to see is:

server.host = "127.0.0.1"
server.port = 8080

The host still comes from the defaults file, while the project's port wins. ConfigStack lets you describe that relationship instead of manually loading the files and combining them yourself.

Build your first stack

use dotcfg::{ConfigStack, DotCfg};

let defaults = DotCfg::new("myapp").at_dir("./config/defaults");
let project = DotCfg::new("myapp").at_dir("./config/project");

let cfg = ConfigStack::new()
    .layer("defaults", defaults)
    .layer("project", project)
    .build()?;

Each call to layer() adds one DotCfg source and gives it a name. Here we called them defaults and project. The names let you refer to a particular source later when you need to.

Order matters

Layers are read in the order you add them. If two layers contain the same setting, the later layer wins. In the example above, project comes after defaults, so its server.port value becomes the one your application reads.

DotCfg or ConfigStack?

If your application has one config file, keep using DotCfg. ConfigStack does not replace it. Use ConfigStack when you genuinely have multiple file-backed configuration sources and need one place to read the final values.

Next, learn how layers are combined, including nested settings and environment variables.