cfgraft v0.3.4 was released on 2026-08-28. This maintenance release focuses on making configuration more flexible while keeping syncs safe. The headline change allows destination mappings to overlap with clear warnings and pre-write collision detection, so users can model nested configuration paths without being blocked by validation errors.

What’s new

The release relaxes destination mapping validation to permit overlapping roots. Previously, cfgraft rejected configurations where two mappings shared a common destination prefix. Now mappings such as ~/.config and ~/.config/nvim can coexist.

When overlaps exist, the TUI surfaces destinationOverlapWarnings for each overlapping pair and notes when a mapping is saved with an overlap warning. Sync planning builds a planned-target index that claims each destination file before any writes. If two sources would resolve to the same destination file, or one source would require a path that another source claims as a directory, planning aborts with an error and no files are written.

Documentation in docs/USAGE.md was updated to describe the new behavior: overlap is allowed, the UI warns, sync succeeds when files remain distinct, and sync aborts on collisions.

The release also includes routine maintenance: Go toolchain updated to 1.26.5 in CI, UI dependencies refreshed, and security scanning added to CI workflows. No breaking changes to the public CLI interface were introduced.

Why it matters

Many dotfile setups naturally overlap. A user may want a broad mapping for ~/.config alongside a more specific mapping for a particular application. The previous strict rejection forced workarounds and made legitimate configurations impossible. With v0.3.4, those configurations load with warnings instead of errors, preserving flexibility while adding a safety net.

Collision detection ensures the permissive change does not introduce risk. Because sync aborts before any writes when a real conflict is detected, users get the freedom to define overlapping mappings without fear of partial or destructive updates. The warnings make overlap visible in the TUI, so users can review and adjust as needed.

Upgrade and install

cfgraft v0.3.4 is available as prebuilt binaries for darwin-amd64, darwin-arm64, linux-386, linux-amd64, linux-arm64, and windows-386 and windows-amd64, with SHA256 and MD5 checksums published on the release page. Building from source requires Go ≥1.26.

Existing configuration files remain compatible. Configs that previously triggered a validation error for overlapping mappings will now load with warnings instead of being rejected. No migration is required.

This post was AI-generated using the model unsloth/Muse-Glimmer-30B-GGUF:Muse-Glimmer-30B-UD-Q6_K_XL. Reference repository UnitVectorY-Labs/cfgraft, release v0.3.4 published 2026-08-28. Article generated 2026-08-28. Author: release-storyteller.