Getting started

Install

Workler needs Node.js >= 18 and git on your PATH.

npm install -g workler
workler help

Initialize the project

Run workler init once in your project root:

workler init

It creates a starter .workler file, the .worktrees/ directory, and makes sure .worktrees/ is ignored by git (via .git/info/exclude, so nothing changes in your committed files):

created .workler
ready   .worktrees
ignored .worktrees/ in .git/info/exclude

init is idempotent — running it again reports exists instead of created and changes nothing.

Declare the rules

Edit .workler to declare what a fresh workspace needs. It is line-based, like .gitignore but with an action first:

link node_modules   # symlink back to the main project
copy .env           # copied into the workspace

• link <path> creates a symlink in the workspace back to the main project — right for big, regenerable directories like node_modules.
• copy <path> copies the file or folder into the workspace — right for local config each workspace may want to change independently, like .env.

See Copy & link rules for the full syntax.

Create a workspace

workler add feature-a

Workler clones the main project into .worktrees/feature-a, creates and checks out a new branch feature-a from the main project's current HEAD, and applies the rules:

cloning /path/to/project
     to /path/to/project/.worktrees/feature-a
create branch feature-a from HEAD
linked node_modules
copied .env
done   feature-a
path   /path/to/project/.worktrees/feature-a

The workspace is a full, independent clone — its own HEAD, index, and local branches — ready to run without an install step.

Not sure what a command will do? Every mutating command takes --dry-run:

workler add feature-b --dry-run

prints the whole plan — clone, branch, every rule — without touching anything.

Move around

workler list                        # every workspace, its branch, its path
cd "$(workler path feature-a)"     # jump into a workspace

Or load the shell helper once and use wcd:

eval "$(workler shell-init)"    # put this in your shell rc
wcd feature-a
wcd main

Everyday commands

Command	What it does
workler add <name>	Clone a new workspace on a new branch, apply rules
workler apply <name>	Re-apply the rules to a workspace
workler list	Show every workspace with its branch and path
workler path <name>	Print a workspace's path (for cd "$(...)")
workler remove <name>	Delete a workspace (refuses if it has uncommitted changes)
workler status	Branch, ahead/behind, clean/dirty for every workspace
workler sync	Fetch everywhere, fast-forward what's safe

See the CLI reference for every command and flag.

Where to go next

• Workspaces & branches — bases, --branch, --checkout, and detached checkouts.
• Copy & link rules — the .workler format in full.
• Keeping workspaces in sync — status, fetch, sync, and branch-sync.
• Programmatic API — create, inspect, list, and remove workspaces from TypeScript or JavaScript.