susu

susu is a small Unix CLI for keeping selected dotfiles in a Git repository and restoring them on another machine. Public files are stored as ordinary snapshots; files added with --sensitive are encrypted before they enter the repository.

susu supports macOS and Linux. It manages dotfile entries and their contents, while Git remains responsible for commits, remotes, synchronization, merges, and history.

Features

• Store individual files or recursively add directories.
• Encrypt sensitive files with one password per repository.
• Share portable HOME and XDG config paths across machines.
• Inspect stored files and restore them with predictable one-way commands.

Installation

Prebuilt archives are published on the GitHub Releases page for:

• Linux (amd64, arm64);
• macOS / Darwin (amd64, arm64).

Every release includes checksums.txt for artifact verification. All binaries are packaged as .tar.gz archives with README.md, LICENSE, and CHANGELOG.md.

macOS Gatekeeper

macOS may block susu because the release binaries are currently unsigned and not notarized.

Try to run susu once. Then open System Settings -> Privacy & Security and click Open Anyway.

Alternatively, remove the quarantine attribute:

xattr -d com.apple.quarantine ./susu

Only do this if you downloaded susu from the official GitHub Releases page.

To install from source, Go 1.26 is required. From the repository root, install with the pinned mise toolchain:

mise install
mise exec -- make install

Or use an already installed compatible Go toolchain:

make install

make install writes susu to GOBIN or the standard Go binary directory. Ensure that directory is on PATH. Run make instead to build ./susu without installing it.

Quick start

Create and select a Git repository, then add the files you want to manage:

mkdir -p ~/src
git init ~/src/dotfiles

susu init ~/src/dotfiles
susu add ~/.zshrc ~/.gitconfig
susu add --sensitive ~/.kube/config

susu ls

git -C ~/src/dotfiles add susu.json public encrypted
git -C ~/src/dotfiles commit -m "Manage dotfiles with susu"

The first sensitive operation asks for a repository password and confirmation. The password is never stored.

On another machine, use Git to retrieve the repository and susu to restore its files:

git clone <repository-url> ~/src/dotfiles
susu init ~/src/dotfiles
susu ls
susu apply

susu apply replaces all managed destination files. Review susu ls and the repository before applying; susu does not create backups or resolve conflicts.

Commands

Command	Purpose
susu init <repository>	Initialize susu in an existing Git repository
susu add [options] <path...>	Capture new files or update managed snapshots, including recursively
susu rm <path...>	Stop managing files
susu ls	List managed files (susu list is an alias)
susu show <path>	Print a stored file
susu apply	Apply managed files to this machine
susu completion <shell>	Generate completions for Bash or Zsh

Generate and activate shell completions for the current session:

source <(susu completion bash)                 # Bash
autoload -Uz compinit && compinit               # Zsh initialization
source <(susu completion zsh)                   # Zsh

Running susu without a command shows a short onboarding before initialization, or the active repository and managed file count afterward. Use susu --help for the complete command overview.

Ordinary susu add <path...> captures new files and refreshes snapshots for exact already-managed logical paths; no update flag is needed. Existing entries keep their source path and sensitivity regardless of --sensitive, which applies only to new entries. Updating an existing sensitive entry asks for one unlock password even without the flag. Recursive adds refresh discovered managed files and add new ones, but do not remove entries missing locally. A different logical path naming the same managed inode is skipped as already managed, without a password solely for that alias. The CLI prints added, updated, and already managed groups. Updates are atomic per file, not a global transaction: committed updates remain after a later failure, and no backups are created. See the reference for addition rollback and failure reporting.

Recursive adds and explicit regular-file or real-directory inputs ignore ~/.kube/cache and everything below it. Sensitive classification is always explicit. The machine-local susu state directory, active repository worktree, and Git common administrative directory are reserved control roots: add rejects inputs that overlap or contain them, and apply refuses manifest destinations that would overlap them.

A little lore

susu comes from the Japanese word susu (すす), meaning “soot”, and is a nod to the Susuwatari, the tiny soot sprites from Hayao Miyazaki's worlds.

It is pronounced roughly su-su: two short, even syllables, without a strong English-style stress.

Susuwatari are small, quiet creatures that live around the house, carrying little things and doing their work mostly out of sight.

That felt appropriate for a small Unix-style tool whose job is to take care of the little configuration files living around your $HOME.

susu does not try to manage your entire system. It tracks an explicit set of dotfiles, stores their snapshots in a repository, restores them to your home directory, and stays out of the way.

Small files. Small tool. One job.

Documentation

• Reference — detailed commands, path behavior, repository format, workflows, and limitations.
• Encryption and security model — encryption design, threat model, operational guidance, and audit status.
• Design and architecture — components, data flow, locking, and filesystem guarantees.
• Changelog — version-specific changes.
• Releasing — maintainer workflow and published artifact matrix.

License

susu is available under the MIT License.