Workspaces & branches

A workspace is a normal local clone of your project, living under .worktrees/<name>. Because it is a real clone — not a git worktree — it has its own HEAD, its own index, its own local branches, and its own fetch state. The main project itself appears in listings as the reserved workspace main.

Creating workspaces

workler add <name> [base] [--branch <branch>] [--checkout <ref>] [--force] [--dry-run]

add clones the main project into .worktrees/<name> (a fast local clone), sets up the branch you asked for, and applies the copy/link rules.

Branch behavior

Command	Result
workler add feat	Creates a new branch feat from the main project's current HEAD and checks it out.
workler add feat main	Creates a new branch feat starting at main. The base may be a local branch, a remote branch (e.g. origin/main), a tag, or a commit. A remote-branch base also sets upstream tracking.
workler add exp --branch feat/x	Workspace named exp, branch named feat/x. Creates feat/x from HEAD if it does not exist, otherwise checks it out.
workler add exp main --branch feat/x	Creates branch feat/x from main, while the workspace remains named exp.
workler add hotfix --checkout main	No new branch: checks out main directly. Tags/commits are checked out on a detached HEAD.

Rules:

• --checkout cannot be combined with --branch or positional [base]. [base] may be combined with --branch to create that explicitly named branch from the base.
• workler add <name> / workler add <name> <base> always create a new branch and fail if branch <name> already exists — use --checkout <name> to reuse the existing branch.
• Workspace names cannot be main, contain path separators, or be made only of dots.

Several workspaces on one branch

git worktree refuses to check out the same branch twice. Workler workspaces are independent clones, so this just works:

workler add review-1 --checkout main
workler add review-2 --checkout main

Both workspaces sit on main, each with its own working tree and index.

What add sets up

Beyond the clone and branch, add configures the workspace so everything else works later:

• git config workler.root points at the main project, workler.name records the workspace name.
• origin is repointed from the local path to the main project's real remote, so git fetch/git push behave as expected.
• A workler-root remote points back at the main project — used by workler branch-sync.
• .worktrees/ is added to the clone's .git/info/exclude, so nested workspaces stay invisible to git.

Uncommitted changes don't come along

A clone only contains committed work. If the main project has uncommitted changes when you add, Workler prints a warning — commit or stash first if the new workspace needs those changes.

Listing and navigating

$ workler list
NAME       BRANCH     PATH
main       main       /path/to/project
feature-a  feature-a  /path/to/project/.worktrees/feature-a
review-1   main       /path/to/project/.worktrees/review-1

workler path <name> prints just the path, made for command substitution:

cd "$(workler path feature-a)"

or use the wcd shell helper.

Removing workspaces

workler remove feature-a

remove deletes the workspace directory — but refuses if the workspace has any local changes, untracked files included: deletion is forever, so even a copied .env counts here. Use --force to remove anyway. The main workspace can never be removed.

Next steps

• Copy & link rules — what gets set up inside each workspace.
• Safety, --force, --dry-run — how conflicts are handled.
• Keeping workspaces in sync — because independent clones drift.