Introduction

What Dotweave is

Dotweave is a command line tool that syncs your dotfiles with git. Pick the config files you want out of your home directory — ~/.zshrc, ~/.gitconfig, and so on — and every machine you work on can have the same setup.

There are three commands to learn. dotweave track registers a path for syncing, dotweave push puts the current contents of your home directory into the sync directory, and dotweave pull takes them back out on another machine. Files you cannot commit as they are, such as an SSH key, go in secret mode and are stored as age ciphertext.

The sync directory is a git repository. Committing it and pushing it to a remote is ordinary git work, done the way you already do it.

Home is the source of truth

Your local files are what matters; the repository is a derived copy. That is the opposite of how symlink and template based managers work. stow replaces files in your home directory with symlinks into a repository. chezmoi keeps the canonical copy in its own store and asks you to edit through it. Both make the repository authoritative, which means your editor, your tools, and your muscle memory have to accommodate the tool.

With Dotweave you edit ~/.zshrc in your editor, with no wrapper command and no symlink. When you want to publish the change, you run dotweave push and then commit with git.

The cost of that choice is that nothing is automatic. There is no daemon and no file watcher, so a change is not shared until you run a command.

What Dotweave does not do

Dotweave does not run git for you. push and pull only move files between your home directory and the sync directory. Committing, pulling, and pushing to a remote are yours to run, and dotweave cd opens a shell in the right place to do it.

Dotweave does not merge. When two machines change the same file, that is a git divergence in the sync repository and you resolve it with git.

Dotweave does not replace your files with symlinks, does not require a special editor, and does not need an external age binary — encryption is built into the CLI.

It does need git on your PATH.

A minimal session

dotweave init
dotweave track ~/.gitconfig
dotweave track ~/.ssh/config --mode secret
dotweave push

At that point ~/.gitconfig is mirrored as a plain file and ~/.ssh/config is mirrored as age ciphertext. To publish, open the sync directory and use git:

dotweave cd
git add -A && git commit -m "Initial sync"
git remote add origin <your-repo-url>
git push -u origin main

On the next machine, clone the repository with your age key and restore:

dotweave init <your-repo-url> --key-file ~/dotweave.agekey
dotweave pull

Implementation and reference

The two-snapshot model behind every command is described in How syncing works, and the files Dotweave creates in Directory and repository layout.

Read Install Dotweave to get the CLI, or How syncing works first if you would rather understand the model before running anything.