Directory strategies

The directory strategy answers one question: where should this application's config live? dotcfg does not merge several locations behind your back—you choose the behavior you want.

Home dot directory

This is the default. It places the application directory directly under your home directory, similar to familiar directories such as .cargo and .ssh.

let cfg = DotCfg::new("mytool");
// ~/.mytool/config.toml

// Equivalent when you want to be explicit:
let cfg = DotCfg::new("mytool").dot();

XDG configuration

Use .xdg() when your application should follow the platform's XDG configuration strategy. dotcfg delegates this resolution to etcetera rather than manually assuming one path on every operating system.

let cfg = DotCfg::new("mytool").xdg();
let path = cfg.file_path()?;

Custom directory Since 0.3.0

.at_dir() bypasses both the dot and XDG strategies. The directory you provide is used exactly as the config directory; dotcfg only appends the configured filename and extension.

let cfg = DotCfg::new("mytool")
    .at_dir("/my/project/.config");

// /my/project/.config/config.toml

Discover a project config Since 0.3.0

find_in_ancestors() was introduced in 0.3.0 for tools that can run from anywhere inside a project. It starts at the current working directory and walks upward. At each level it looks for .mytool/config.toml (or your selected filename and format).

let project = DotCfg::new("mytool")
    .find_in_ancestors()?;

match project {
    Some(cfg) => println!("Found {:?}", cfg.file_path()?),
    None => println!("No project config found"),
}

The starting directory itself is checked first. If nothing is found, the method returns Ok(None); it does not silently fall back to your home or XDG directory.

Start somewhere specific Since 0.3.0

find_in_ancestors_from() is the same search with an explicit starting path. This is useful when your program already knows the project path, and it makes tests deterministic.

let cfg = DotCfg::new("mytool")
    .find_in_ancestors_from("/tmp/project/src")?;

Which should I use?