Git and worktrees

Checkout or worktree

Each thread in a project works in one of two places.

Local checkout

Your repository folder, on whatever branch you have checked out. The agent edits the same files you do, and so does every other thread on the checkout.

Worktree

A separate folder with a branch of its own, linked to the same repository. The thread's edits stay out of your checkout until you bring them over.

Use the checkout for small changes you want to run and try right away. Use a worktree when several threads work on one project at once, or when you want the work kept apart until you have reviewed it.

Choose for each thread

1. Start a new thread with ⌘N.
2. Under the composer, click the line that says where the thread works, such as Works in the local checkout on main, and pick Local checkout or Worktree. With a worktree, the line reads Starts on a new branch from main.
3. Send your first message. A worktree is created now, before the agent starts.

New threads start with the location set in Settings under General, New thread workspace: Local checkout or Isolated worktree. Tasks have their own Execution location, and schedules a Works in field. Forks, subthreads, and threads an agent starts with thread_start work in the same folder as the thread they came from.

A thread's menu starts with the branch it works on, marked Worktree or Checkout. In the sidebar, each thread's row names its project, then its branch or worktree.

How a worktree is made

Before the agent starts, OpenOrc copies your .env and .env.* files into the new folder, sets up any submodules, and runs the project's setup script. Change the prefix, the copied files and the script on the project's Settings tab: press ⌘K, choose the project, then Settings.

Move a thread

Open the thread's menu, from the three-dot button in its header or by right-clicking it in the sidebar. Its first row names the thread's branch, marked Worktree or Checkout. Point at it and choose Move to a worktree or Move to the checkout. A dialog lists every file that will move. Moving doesn't start an agent, and you can't move a thread while its agent is working.

• Move to a worktree takes every uncommitted change in the checkout, including yours and other threads', into a new worktree on its own branch. The worktree starts at the checkout's current commit. Those files in the checkout then go back to its last commit.
• Move to the checkout merges everything the worktree changed since it started, committed or not, into your checkout's files, unstaged. Then the worktree is removed. Its branch stays, with any commits made on it.

If a file changed in both places in ways Git can't combine, nothing moves and the dialog names the files. A move also stops when a file's staged version differs from the file on disk; commit or unstage it first.

Bring the work back

Move to the checkout puts a worktree's changes in your own files, to keep editing or to commit yourself. You can also commit in the worktree, push the branch and open a pull request (see Push and open a pull request), or merge the branch into your checkout with Git, for example git merge openorc/fix-the-login-redirect-3f2a91. Only committed work is on the branch, so commit in the worktree before you merge.

Remove a worktree

Worktrees take disk space, mostly from installed dependencies and build output. Remove worktree, in the branch row's submenu of the thread's menu, removes the folder and keeps the thread. OpenOrc commits the worktree's uncommitted changes to its branch first, as deleting does, and the branch and the conversation stay. The thread's next message makes the worktree again on that branch. Files Git ignores in the folder are deleted, so the project's setup script runs again.

To remove many at once, open Settings, then Data, and choose Clean up… beside Worktrees. It lists every worktree on this Mac by project with its size, and ticks those whose thread is resolved or whose pull request is merged or closed. A worktree whose agent is working, waiting on you, or running a background command can't be removed until it stops, and neither can one that follows a cloud sandbox or one a legacy task shares.

Delete a thread

Delete thread, in the thread's menu, removes the conversation and its worktree:

1. OpenOrc commits the worktree's uncommitted changes to its branch, with the message "Save uncommitted work before removing the worktree".
2. It removes the worktree folder. Ignored files in it, such as a copied .env, go with it.
3. The branch stays, with all its commits.

If that commit fails, for example because Git has no user name set, nothing is deleted. Deleting never touches your checkout, and tasks the thread created stay. Resolving a thread keeps its worktree. A worktree shared with a fork, a subthread, or a helper thread goes only with the last thread that uses it.

What OpenOrc adds to your repository

• Branches under openorc/, or your Branch prefix, one for each thread that used a worktree.
• Worktree registrations under .git/worktrees/. The folders themselves live in OpenOrc's data folder, never inside your repository.
• Refs under refs/openorc/ that keep saved file states from being cleaned up by Git: checkpoints/ for each thread's turns, which Undo and the change cards use, and snapshots/ for tasks that run on their own. They go when you delete the thread or task. Moves and patch exports hold a ref only while they run. These refs point at trees, so git log --all skips them and git for-each-ref refs/openorc lists them.
• Commits you make from OpenOrc, and the commit that saves a worktree's work before it is removed.
• Remote-tracking refs from fetching a worktree's starting branch, and the upstream that pushing sets.
• For a pull request a model reviews, a worktree of the pull request on no branch, and the fetched commits.

OpenOrc installs no hooks and doesn't edit .gitignore or .git/info/exclude. It never runs git stash or git rebase, and never force-pushes.

Projects without Git

OpenOrc reads a project folder's Git state each time it needs it, so you can run git init or make a first commit later without adding the project again.

When a worktree isn't possible, the location menu says why, such as Worktrees need git and a first commit. Workspace conversations always work in a plain folder. See Threads.

Next steps