Work on a branch in a worktree

A worktree is a second checkout of your repository on its own branch. Use one to let the agent work on a change while you keep your main folder as it is, or to run two tasks side by side. Each worktree has its own Haarness server and its own chats.

Create a worktree and open it

From inside your repository:

haarness worktree create review-fix --from main
haarness worktree open review-fix

create makes a new branch from main and checks it out in a new folder. It prints the folder's path. open starts the terminal UI in that worktree.

Without --from, the worktree starts from the branch checked out in your main folder. Haarness names the branch haarness/review-fix-… unless you pass --branch, and puts the folder inside Haarness's data folder unless you pass --path. The new branch does not track a remote branch. Worktrees need the project to be a Git repository.

To get the path for another tool:

cd "$(haarness worktree open review-fix --path-only)"

See your worktrees

haarness worktree list

This lists each project with its main folder and worktrees, with their branches. * marks the one you are in, and missing one whose folder is gone. Commands that act on a worktree take its name, path or ID.

In the terminal UI, /worktree lists them and can create, open, reset and remove worktrees. In Desktop, use the location button above the message box; see Work in a separate worktree.

Start over

haarness worktree reset review-fix --confirm

This moves the worktree's branch back to the ref it was created from, such as main as it is now, and discards the commits made on it. Pass --to <ref> to reset to something else.

If the worktree has uncommitted changes to tracked files, reset stops. Add --discard-changes to throw them away, and also --remove-untracked to delete untracked files. Ignored files are always kept.

Remove a worktree

haarness worktree remove review-fix --confirm --delete-branch

This deletes the worktree's folder. --delete-branch also deletes the branch, but only if Git says it is merged; otherwise the branch is kept and the output says so.

If the worktree has uncommitted or untracked changes, removal stops. Add --discard-changes to remove it anyway.

What reset and remove will not do

• Act without --confirm.
• Act while a Haarness server is running in that worktree. Close its terminal UI, or stop the server with haarness serve --stop --workspace <path>.
• Remove the worktree you are standing in. Run the command from another folder.
• Touch folders you created yourself. Only worktrees made by Haarness can be reset or removed.

Reference

Related

• Find and resume a chat
• Review changes