Directory Structure

Everything dotweave creates lives under a single directory: ~/.config/dotweave/. When you run dotweave init, this structure is set up for you automatically.

---

The Full Picture

• Directory~/.config/dotweave/

  • settings.jsonc
  • keys.txt
  • Directoryrepository/

    • manifest.jsonc
    • Directorydefault/

      • .gitconfig
      • .zshrc
      • Directory.config/

        • Directorynvim/

          • init.lua
    • Directorywork/

      • Directory.config/

        • Directorywork-tool/

          • config.json
      • Directory.ssh/

        • config.dotweave.secret

---

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-.

Caution

Back up your keys.txt somewhere safe — a password manager works great. If you lose it, you won’t be able to decrypt your secret files.

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)

Note

You rarely need to edit manifest.jsonc by hand. The dotweave track and dotweave untrack commands handle it for you.