Isolate work with worktrees

A worktree adds another working directory to the same Git repository. Use one when concurrent tasks need independent file changes—for example, fixing a bug while developing a feature.

A regular New task starts a separate conversation in the same project folder. A worktree separates the files into another folder. New worktrees start at the selected branch or commit with detached HEAD, so you can create the working branch later. Worktrees are available only for Git repositories.

Create a worktree for a new chat

Select a Git project.
Open New task, then select the gear beside the composer.
Turn on New worktree.
Choose the branch to start from.
Enter the first request and send it.

Choosing options does not change Git immediately. Sending the first message starts worktree creation and shows preparation, checkout, and setup progress in the conversation. Expand Show details to inspect output, or choose Cancel, Don’t use worktree, or Try again when needed.

With New worktree off, choosing a branch switches the current project folder before the first message is sent. If the switch fails, your text and attachments remain in the composer.

Choose the starting work

Open the existing dialog from New worktree in the project menu to choose one of these starting points.

Starting point	Included content
Branch or commit	Uses tracked files at that point. Uncommitted changes and untracked files from the current folder are not copied.
Start from the current workspace	Copies uncommitted changes and untracked files from the current folder. Copied changes are not staged, and Git-ignored files are excluded.

The available choices vary by entry point, so confirm the starting point and whether current changes are included.

Working-location menu for querypie-ai-docs with the ella/aru-manual root and jammy-hedgehog worktree

Before starting work, check the current HEAD and directory. Dependencies and development servers may need to be set up again in the new folder.

Check the working location

Make sure file links, the Files panel, and the terminal point to the new worktree directory. Changes in another worktree do not automatically appear in the current folder.

Environment	Example work
Original project folder	Review the current state and continue existing work
`fix/login-error` worktree	Fix and test a login error
`feature/report-export` worktree	Build report export

Bring changes into an existing branch

Review the changed files and test results, then use the normal Git commit and merge process. Creating or completing a worktree does not merge its changes into another branch.

If the worktree starts with detached HEAD, create a branch in the Git view or run git switch -c <branch-name> in the terminal before committing. This does not push the branch automatically.

When asking Aru to integrate the work, name both the destination branch and the changes to bring in. If there is a conflict, review and resolve it before continuing.

I want to merge the completed changes from fix/login-error into main. First review the changes and test results, then show me the commits and any conflicts before merging.

You can also merge from Changes → Update branch. Open the destination branch, choose the source branch, and confirm the direction shown on screen.

Update branch screen with Merge, Rebase, a source branch, and the Merge button

The screenshot shows a general example that brings origin/main into the current main. For worktree changes, choose the worktree branch as the source and confirm the destination branch.

Remove a worktree

Removing a worktree cleans up its working directory. Deleting the branch is a separate choice; review both targets in the confirmation screen.

Before removal, check uncommitted changes and any result files you need. The root or current worktree may not be removable. If removal fails or the directory is missing, inspect the folder and Git state first.

See Review changes to compare modified files.