Copy & link rules

The .workler file at the project root declares what every fresh workspace needs. It is applied automatically at the end of workler add, and can be re-applied at any time with workler apply.

The format

Line-based, like .gitignore but with an action first:

# full-line comment
link node_modules   # inline comment
copy .env
copy "some folder/file.txt"
copy 'another file.txt'

Each line is <action> <path>:

• link <path> creates a symlink in the workspace pointing back to the main project's copy.
• copy <path> copies the file or folder into the workspace.

Blank lines are ignored. A # at the start of a line or preceded by whitespace starts a comment; a # inside a quoted path (or glued to a word, like file#1.txt) does not. Quote a path with double or single quotes if it contains spaces or #.

Choosing link vs copy

	link	copy
Best for	Big, regenerable directories: node_modules, build caches	Local config a workspace may change: .env, local databases
Disk cost	None — one shared copy	Full copy per workspace
Independence	Changes are shared with the main project	Each workspace has its own

A linked node_modules means a new workspace runs instantly with zero extra disk — but an npm install in any workspace changes the shared directory for everyone. Copy instead if workspaces need different dependency states.

Path restrictions

Paths must stay inside the project. The parser rejects, with the line, column, and offending line content:

• absolute paths
• paths containing ..
• .git
• .worktrees

.workler:3:6: paths with ".." are not allowed: "../outside"
  3 | copy ../outside

How rules are applied

For each rule, the destination inside the workspace is inspected first:

• Source missing → the rule is skipped with a note (skip ... source does not exist). This is fine — e.g. link node_modules before anyone has run npm install.
• Already correct → reported as ok and left alone. A symlink that already points at the right source counts as already linked; a copy whose destination content matches the source counts as up to date.
• Fresh → the symlink is created (linked) or the content copied (copied).
• Anything else — a symlink pointing elsewhere, a regular file, a directory — is a conflict. Nothing is overwritten; see Safety, --force, --dry-run.

Symlinks are created relative, so a workspace keeps working if the whole project directory moves. On Windows, directory links are created as junctions (no elevation needed).

Re-applying rules

Rules are applied when a workspace is created, but you can refresh at any time — after editing .workler, or after .env changed in the main project:

workler apply feature-a          # one workspace
workler apply --all              # every workspace
workler apply                    # run inside a workspace: refresh from its parent
workler apply feature-a --dry-run

apply follows the same conflict rules as add: an up-to-date destination is ok, a differing one is a conflict until you pass --force.

Commit the file

.workler is meant to be committed — it documents what a working checkout needs, and nested workspaces read the copy checked out in their parent workspace.