We are excited to announce the official launch of cfgraft on June 2, 2026. For anyone who has managed their system configurations or “dotfiles” via Git, the struggle is familiar: you want the version control and portability of a repository, but you dread the moment a blind git pull or a naive sync script overwrites a critical local tweak you forgot to commit.

cfgraft is designed to solve this exact problem, providing a robust, Unix-style bridge between your Git-based configurations and your local filesystem.

What is cfgraft?

At its core, cfgraft is a synchronization tool that treats a Git repository as the source of truth but respects the reality of your local machine. Unlike traditional methods that rely on symlinks or simple copying, cfgraft implements state-based safety.

By tracking content hashes of the files it manages, cfgraft can detect “drift”—when a local file has been modified independently of the source repository. Instead of silently overwriting your changes, cfgraft flags these as conflicts, giving you full control over whether to preserve your local modifications or overwrite them with the latest version from Git.

Powerful Interfaces for Every Workflow

Whether you prefer the efficiency of a script or the intuition of a visual interface, cfgraft provides the right tool for the job.

The CLI: Automation and Precision

For those who live in the shell, cfgraft offers a powerful set of commands:

  • sync: The primary engine for updating your system. It refreshes repository caches and applies changes. With flags like --dry-run, you can preview exactly what will happen before a single byte is changed on your disk.
  • diff: Get a clear, unified-style view of the differences between your Git source and your local destination, ensuring you know exactly what is changing.

The TUI: Interactive Management

For a more visual experience, cfgraft includes a sophisticated Terminal User Interface (TUI) built with Bubble Tea. The TUI transforms configuration management into an interactive process, allowing you to:

  • Effortlessly add, edit, and remove sources and mappings.
  • Use path autocomplete and real-time validation to ensure your mappings are correct.
  • Monitor background sync and diff operations with real-time progress indicators.

Why it Matters

The real value of cfgraft lies in the peace of mind it provides. By separating the source (Git) from the state (local hashes), it eliminates the “fear of the sync.”

You can confidently map entire directories, preserve executable bits, and even automatically clean up local files that have been removed from the source repository—all while knowing that your unique local customizations are safe from accidental erasure.

Getting Started

cfgraft is available as pre-compiled binaries for macOS, Linux, and Windows, making it easy to get up and running without worrying about build dependencies.

To begin, simply define your sources and mappings in ~/.config/cfgraft/config.yaml and run cfgraft sync. For those who prefer a guided experience, just run cfgraft without any arguments to launch the TUI.

Transparency Note: This post was AI-generated using the model unsloth/gemma-4-31B-it-GGUF:UD-Q5_K_XL.