dotweave track · Dotweave

Synopsis

dotweave track [--kind file|directory] [--mode mode|platform=mode]... [--permission octal|platform=octal]... [--profile profile]... [--local platform=path]... [--repo path|platform=path]... <target>...

Record a file or directory in manifest.jsonc so push and pull can mirror it between your home directory and the sync directory.

Arguments

Argument	Type and default	Purpose
`target`	`string`, one or more required	Local files or directories under your home directory to track, including cwd-relative paths or repository paths inside tracked directories.

Flags

Flag	Type and default	Purpose
`--kind`	`file` or `directory`, single value, none	Target kind to use when the path does not exist yet.
`--mode`	`mode` or `platform=mode`, repeatable, none	Sync mode for the tracked target: `normal`, `secret`, or `ignore`.
`--permission`	`octal` or `platform=octal`, repeatable, none	File permission to restore, as a four-character octal value such as `0600`. Has no effect on Windows.
`--profile`	`profile`, repeatable, none	Restrict syncing to registered profiles. A single empty value, `--profile ""`, clears the assignments instead.
`--repo`	`path` or `platform=path`, repeatable, none	Repository-relative path under the profile namespace. Valid with exactly one target.
`--local`	`platform=path`, repeatable, none	Platform-specific local path override. A bare value with no `platform=` prefix is rejected.

Every boolean flag also accepts a --no- form. track registers no boolean flags, so none applies here.

Platform-scoped flag syntax

--mode, --permission, --repo, and --local accept the keys default, win, mac, linux, and wsl. A bare value with no key sets default, so --mode secret and --mode default=secret mean the same thing.

Repeat a flag to cover several platforms at once, as in --mode normal --mode win=ignore. Repeating the same key for one flag fails with DUPLICATE_PLATFORM_FLAG, and an unrecognized key fails with INVALID_PLATFORM_FLAG. --local requires an explicit key, and --permission requires a default value whenever it is used at all.

Behavior

Tracking a new path appends one entry to manifest.jsonc and prints the resolved fields.

dotweave track ~/.gitconfig

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

Flags that carry a value widen the printed key column.

dotweave track ~/.ssh/config --mode secret --permission 0600

✔ Started tracking .ssh/config
  kind        file
  path        /home/you/.ssh/config
  repo        .ssh/config
  mode        secret
  permission  0600

Running track again on an already-tracked path updates only the fields you name and preserves the rest, so dotweave track ~/.ssh/config --profile work keeps the mode and permission set earlier.

When the target is not an existing manifest entry and you passed no --repo, track instead sets the sync mode or profiles of a nested path inside an already-tracked directory, creating a child override entry. The output then reads Updated sync mode for <path> or Sync mode unchanged for <path>. This is the only way to adjust a path nested inside a tracked directory.

A child entry overrides its parent directory entry. Each of mode, permission, and profiles inherits independently from the nearest ancestor directory entry, so a child that sets only mode still inherits the parent's permission and profiles.

Targets must resolve inside your home directory, may not be the home directory itself, may not overlap the sync directory, and may not contain keys.txt.

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

Errors

track fails when a path that does not exist yet is passed without --kind, when --kind disagrees with the path on disk, and when the resolved local or repository path collides with an existing entry. It also fails when the target leaves your home directory, overlaps the sync directory, or contains the age identity file. Passing --repo with anything other than one target fails with REPO_PATH_TARGET_COUNT, and an unregistered profile name fails with UNKNOWN_PROFILE. Read Error messages for each message and its fix.

Read Track files and directories for the task-oriented walkthrough, or Sync modes to choose between normal, secret, and ignore before you register anything.