Directory Structure

Everything dotweave creates lives under a single app-data directory. On Linux, macOS, and WSL this defaults to $XDG_CONFIG_HOME/dotweave, or ~/.config/dotweave when XDG_CONFIG_HOME is unset. On Windows it defaults to %APPDATA%\dotweave, then falls back to %LOCALAPPDATA%\dotweave, %USERPROFILE%\AppData\Roaming\dotweave, and finally the OS home directory's AppData\Roaming\dotweave.

The Full Picture

• <dotweave-home>

  • settings.jsonc
  • keys.txt
  • repository

    • manifest.jsonc
    • default

      • .gitconfig
      • .zshrc
      • .config

        • nvim

          • init.lua
    • work

      • .config

        • work-tool

          • config.json
      • .ssh

        • config.dotweave.secret

DOTWEAVE_HOME

Set DOTWEAVE_HOME to override the app-data directory for dotweave only:

DOTWEAVE_HOME=/path/to/dotweave dotweave sync

The sync repository is stored under $DOTWEAVE_HOME/repository.

What Each File Does

repository/ — the sync directory

This is a Git repository that holds all your synced files. When you run dotweave push, files are copied here. When you run dotweave pull, files are restored from here. You can push this repository to a remote like GitHub to sync across machines.

repository/manifest.jsonc — the config file

The manifest is the source of truth. It lists every file and directory you're tracking, along with options like sync mode, profiles, and permissions. All dotweave track and dotweave untrack commands modify this file.

repository/default/ — artifacts for the default profile

Files that aren't assigned to a specific profile are stored here. This is where most of your dotfiles will end up.

repository/<profile>/ — artifacts for named profiles

If you use profiles, each profile gets its own subdirectory. For example, entries tracked with --profile work are stored under repository/work/.

keys.txt — age identity file

Your age private key for encrypting and decrypting secret files. This is created during dotweave init. It starts with AGE-SECRET-KEY-.

settings.jsonc — user preferences

Stores your active profile and other local settings. You usually don't edit this directly — commands like dotweave profile use work update it for you.

What manifest.jsonc Looks Like

Here's a simple example with a few tracked entries:

{
  "version": 7,
  "age": {
    "recipients": ["age1ql3z7hjy54pw3hyww5ayyfg7zqgvc7w3j2elw8zmrj2kg5sfn9aqmcac8p"]
  },
  "entries": [
    {
      "kind": "file",
      "localPath": { "default": "~/.gitconfig" }
    },
    {
      "kind": "directory",
      "localPath": { "default": "~/.config/nvim" }
    },
    {
      "kind": "file",
      "localPath": { "default": "~/.ssh/config" },
      "mode": { "default": "secret" },
      "profiles": ["work"]
    }
  ]
}

Manifest structure

• version — schema version (currently 7). Dotweave manages this automatically.
• age — encryption config. The recipients array lists public keys used to encrypt secret files.
• entries — the list of tracked files and directories. Each entry can have:
  • kind — "file" or "directory"
  • localPath — where the file lives on your machine (supports platform-specific paths)
  • repoPath — custom path inside the sync directory (optional, derived from localPath by default)
  • mode — sync mode: "normal", "secret", or "ignore" (optional, defaults to "normal")
  • profiles — which profiles this entry belongs to (optional, global if omitted)
  • permission — file permission in octal like "0600" (optional)