Platform-Specific Paths

Most config files live at different paths depending on your operating system. VS Code settings, for example, are stored in ~/.config/Code/User/ on Linux but ~/Library/Application Support/Code/User/ on macOS. dotweave handles this with platform-specific path objects in your manifest.jsonc.

Platform keys

Every path field in manifest.jsonc can be either a plain string or an object with one or more platform keys:

Key	Matches
linux	Native Linux
mac	macOS
win	Windows
wsl	Windows Subsystem for Linux
default	Any platform not explicitly listed

How resolution works

When dotweave reads a path, it picks the best match in this order:

1. Exact platform key — if your OS has a dedicated entry, that wins.
2. Fallback — wsl falls back to linux if no wsl key exists.
3. default — used when no other key matches.

If none of these resolve, the entry is skipped on that platform.

localPath — always a platform object

localPath tells dotweave where a file lives on your machine. Because this is the field most likely to differ across operating systems, it is always written as a platform object:

{
  "localPath": {
    "default": "~/.config/Code/User/settings.json",
    "mac": "~/Library/Application Support/Code/User/settings.json",
    "win": "%APPDATA%/Code/User/settings.json"
  }
}

repoPath — usually the same, but can differ

repoPath is the path inside the sync directory. Most of the time it’s identical across platforms, so a plain string is fine. If you need it to vary, use the same platform object format:

{
  "repoPath": {
    "default": "vscode/settings.json",
    "win": "vscode-win/settings.json"
  }
}

mode — per-platform behavior

You can also set mode per platform. This is handy when a config only makes sense on certain operating systems:

{
  "mode": {
    "default": "copy",
    "win": "ignore"
  }
}

With this setup the file is synced everywhere except Windows, where it is silently skipped.

Full example

Here’s a complete entry for VS Code settings that works on Linux, macOS, and Windows:

{
  "localPath": {
    "default": "~/.config/Code/User/settings.json",
    "mac": "~/Library/Application Support/Code/User/settings.json",
    "win": "%APPDATA%/Code/User/settings.json"
  },
  "repoPath": "vscode/settings.json",
  "mode": "copy"
}

Tip

When you run dotweave track, the file’s path is recorded under the default key automatically. If you need platform-specific paths, edit manifest.jsonc directly and add the extra keys.

Editing tips

• You can always hand-edit manifest.jsonc to add or adjust platform keys.
• dotweave track is a quick way to start — it captures the current platform’s path as default, and you can add other platforms later.
• Use dotweave status to verify that paths resolve correctly on the current machine before pushing.