Git worktrees
Git worktrees provide separate directories and checked-out branches for one repository, making them useful for parallel tasks. They share Git objects, not one freely writable checkout. Processes, ports, and dependencies require their own isolation.
Choose a source
Identify the parent workspace, path, and branch in the project's worktree list before creating a child. Parent-child metadata organizes tasks; verify the actual directory, branch, and files.
Record the source state first:
git status --short --branch
git worktree list
Determine which uncommitted files the task needs. Creating a worktree does not prove those files were copied; check its inputs after entering the new directory.
Verify creation
- Enter a task-specific name and submit one creation request.
- Wait for its result and check the returned path, branch, and relationship.
- Open a new session only in the confirmed directory.
- Check dependencies, environment, build output, and service ports before working.
Closing the creation dialog does not cancel background creation. For a pending or unknown outcome, inspect the original request through the result-check action instead of repeatedly creating directories.
Distinguish creation from relationship state
| Result | Action |
|---|---|
| Created | Inspect the actual directory, then open a session |
| Directory created but relationship save failed | Check directory and Git state, then repair the relationship without creating another directory |
| Failed without a committed creation result | Use the retry action provided by the UI |
| Unknown result or changed instance | Inspect the original request and current list before assuming success or failure |
Verify request state and directory state separately. Retrying must not overwrite a successfully created workspace.
Work in isolation
Use a terminal scoped to each worktree. Allocate separate development ports and inspect dependency links, environment files, and local databases. Directory separation alone does not isolate runtime resources.
Before sharing identity, credentials, or writable data, establish ownership and concurrency rules. Do not copy an entire user checkout to move a task or include another worktree's artifacts in a commit.
Example: isolate an interface fix
The parent project contains unfinished feature work and a menu needs an independent fix. Run git worktree list in the parent and check its branch, then create a child named menu-fix through the project's worktree entry. The relationship name organizes tasks; the actual branch and directory come from the creation result.
In the returned directory, run:
git rev-parse --show-toplevel
git branch --show-current
git status --short --branch
Confirm the separate directory and required source, then prepare dependencies according to the repository instructions. Uncommitted parent work must not silently become task input. Use a separate server port without stopping the parent's service.
After the fix, review and deliver from the child directory, then verify that parent edits and services remain intact. Transfer commits through the repository's merge or PR process; copying the entire workspace is not code integration.
Finish and clean up
Review, verify, and deliver the changes through the project's process before removing a directory. Check uncommitted files, unpushed commits, untracked artifacts, and running processes. Closing a task window or archiving a chat does not establish that work has been saved.
See Develop in a project for acceptance steps.
Remove a working directory through Git
After preserving needed files and commits and accounting for processes, inspect and remove the completed worktree from another working directory:
git worktree list
git worktree remove /absolute/path/to/completed-worktree
Replace the example path with the verified directory. If Git refuses removal because of changes, preserve or resolve them before continuing, without adding force options. Manually deleting a directory does not reconcile project relationship records.