The .workler file

.workler lives at the project root and declares the copy/link rules applied to every workspace. workler init creates a commented starter file.

Syntax

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'
copy file#1.txt     # a "#" glued to a word is part of the path

Each non-empty line is:

<action> <path>

Actions

Action	Effect in the workspace
link <path>	Create a symlink pointing back to the main project's <path>. Relative on POSIX; directory junctions on Windows.
copy <path>	Copy the file or folder (recursively, preserving timestamps) into the workspace.

Comments

• A # at the start of a line or preceded by whitespace starts a comment that runs to the end of the line.
• A # inside a quoted path, or glued to a word (like file#1.txt), is part of the path.
• Blank lines are ignored.

Quoting

Quote a path with double or single quotes if it contains spaces or #:

copy "some folder/file.txt"
copy 'my #1 notes.md'

Path rules

Paths are relative to the project root and must stay inside the project. Rejected:

Rule	Error
Absolute path	absolute paths are not allowed: "..."
Contains ..	paths with ".." are not allowed: "..."
.git	managing .git is not allowed
.worktrees	managing .worktrees is not allowed
Empty path	empty path

Errors

Parse errors report the line, the column, and the offending line content:

.workler:2:6: unterminated "..." quoted path
  2 | copy "some folder

Other parse errors include unknown action "...", missing path after "copy", and unexpected text after quoted path: "...".

Semantics worth knowing

• Missing sources are skipped, not errors. link node_modules before an npm install just reports skip — re-run workler apply later.
• Order doesn't matter; each rule is independent.
• Rules are read from the parent. A workspace is set up from the .workler of the project that contains it — for nested workspaces that is the .workler checked out in the parent workspace, so commit the file if nested workspaces should inherit the rules.
• Existing destinations are never overwritten without --force — see Safety.