Track files and directories

Tracking records a path in manifest.jsonc so that push and pull know about it. The sections below are independent options rather than steps, so read the one that matches what you need.

Track a file or directory

Pass one or more paths under your home directory to dotweave track. The argument is variadic, so several targets in one call are fine.

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

✔ Started tracking .gitconfig
  kind  file
  path  /home/you/.gitconfig
  repo  .gitconfig
  mode  normal

track writes manifest.jsonc and nothing else. No file is copied into the sync directory until you run dotweave push.

Tracking a path that is already tracked updates only the fields you pass and preserves the rest. That lets you change one entry's mode later without repeating its --repo or --profile values.

A single empty --profile value clears a target's profile assignments, which returns the entry to applying under every profile:

dotweave track ~/.config/my-tool --profile ""

The target must resolve inside your home directory, and it cannot be the home directory itself. It also cannot overlap the sync directory or contain keys.txt, because Dotweave refuses to mirror its own state or your age key material.

Track a path that does not exist yet

You can create an entry before the file exists, so that a later dotweave pull puts it in place. Because there is nothing to inspect, --kind file or --kind directory is required.

dotweave track ~/.config/my-tool/settings.json --kind file

--kind is also checked against a path that does exist. The command fails when the value disagrees with what is on disk, so it cannot silently record a directory as a file.

Override the repository path

By default an entry's repository path mirrors the target's path relative to your home directory. --repo sets that path yourself, which is useful when the local location is long or machine-specific.

dotweave track ~/Projects/scripts/deploy.sh --repo scripts/deploy.sh

--repo is valid with exactly one target. Passing it alongside two or more targets fails, since one repository path cannot describe both. Platform-scoped forms such as --repo win=path are documented on dotweave track, and the resolution rules on Platform-specific paths.

Adjust a nested path inside a tracked directory

track has a second meaning. When the target is not an existing manifest entry and you did not pass --repo, it sets the mode or profiles of a nested path inside an already-tracked directory, creating a child override entry for that path alone.

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

✔ Updated sync mode for .config/my-tool/credentials.json
  mode  secret

The second call reports Updated sync mode for ..., or Sync mode unchanged for ... when the path already resolves to that mode.

A child entry wins over its parent, and the parent's directory walk skips every path a child owns. The file is therefore mirrored once, under the child's mode, not twice. Use the same mechanism with --mode ignore to leave one file out of an otherwise tracked directory.

Stop tracking a target

dotweave untrack ~/.gitconfig

✔ Stopped tracking .gitconfig
  plain: 1
  secret: 0

The two counts report how many plain and secret artifacts were removed. Commit the deletion with git afterward, the same way you commit a push.

To drop only a nested override and keep its parent directory tracked, pass the repository-relative child path:

dotweave untrack .config/my-tool/credentials.json

Implementation and reference

Every flag, its type, and its default are listed on dotweave track and dotweave untrack. The fields these commands write are described on manifest.jsonc.

Read Sync modes to pick the mode value for an entry, or Push, review, and commit day to day once the paths you care about are tracked.