Sync Modes · Dotweave

Every tracked entry has a sync mode that controls how dotweave handles it during push and pull. There are three modes to choose from: normal, secret, and ignore.

At a Glance

Mode	Stored in sync directory	Encrypted	Synced on push/pull
`normal`	Yes	No	Yes
`secret`	Yes (`.dotweave.secret` suffix)	Yes (age)	Yes
`ignore`	No	—	No

normal (default)

Files are copied to the sync directory exactly as-is. No transformation, no encryption — what you see is what you get.

dotweave track ~/.gitconfig
dotweave track ~/.config/starship.toml
dotweave track ~/.config/nvim

Great for: shell configs (.zshrc, .bashrc), editor settings, Git config, tool configs like .tmux.conf or starship.toml — basically anything that doesn't contain secrets.

secret

Files are encrypted with age before being stored in the sync directory. The stored file gets a .dotweave.secret suffix.

dotweave track ~/.ssh/config --mode secret
dotweave track ~/.config/gh/hosts.yml --mode secret
dotweave track ~/.aws/credentials --mode secret

Great for: SSH keys and config, API tokens, .env files with real credentials, GPG keys — anything you wouldn't want exposed if your repository went public.

During pull, dotweave decrypts the file with your age private key before writing it to disk. See Syncing Secrets for the full setup guide.

Caution

Secret mode encrypts the file content, but the filename and path are still visible in the sync directory. Keep that in mind if the path itself is sensitive.

ignore

The entry stays in manifest.jsonc but is skipped during local snapshot and pull. Nothing is read from or written to your home directory for that entry.

During push/status, an ignored entry prunes existing repository artifacts that it solely owns. If ignore is only a platform-specific override and another platform still owns the same repo path as normal or secret, that artifact is preserved.

dotweave track ~/.config/some-tool/cache --mode ignore
dotweave track ~/.local/share/generated-config --mode ignore

Great for:

Temporarily disabling an entry without removing it from the sync config
OS-specific files that shouldn't sync on the wrong platform
Machine-specific configs you want to remember but not replicate

Changing a Mode

Run dotweave track again with the new --mode flag. The existing entry gets updated:

# Originally tracked as normal
dotweave track ~/.ssh/config

# Upgrade to secret
dotweave track ~/.ssh/config --mode secret

Per-Entry Overrides

You can mix modes within a tracked directory. For example, track a directory as normal but override a specific child as secret:

dotweave track ~/.config/my-tool
dotweave track ~/.config/my-tool/credentials.json --mode secret

The directory is synced normally, but credentials.json inside it gets encrypted. Child entries always take priority over their parent.