--- title: Isolate a task with a worktree description: >- Create a separate task directory in Onevium, choose starting branches and nested repositories, and review changes before merging them. canonical_url: 'https://onevium.com/docs/worktrees' language: en updated_at: '2026-10-04' publisher: Onevium minimum_version: 1.2.4 --- > Source: Onevium official documentation > Article: Isolate a task with a worktree > Original URL: https://onevium.com/docs/worktrees > Language: English > Updated: 2026-10-04 > Applies to: 1.2.4+ --- # Isolate a task with a worktree Create a separate task directory in Onevium, choose starting branches and nested repositories, and review changes before merging them. A worktree is another working directory for the same Git repository. Use one to let AI try changes while keeping your work in the original directory. An ordinary local conversation uses the original directory; a new worktree task gets its own directory and branch. ## 1. Start a worktree conversation 1. Create a new conversation in the intended project and check its path. 2. Enable **Worktree** on the right of the project and branch row beside the composer (Figure 1). 3. Click **Start from**. Usually, keep **Current branch**; choose **Other branches…** for a different starting version. Select **Include uncommitted local changes** only when you want to continue edits that have not been committed in the original directory. 4. Send the first message. Onevium now creates the directory and a `onevium/…` branch, prepares the workspace, and starts the task. ![The Worktree checkbox is enabled above the composer, with the Start from menu showing the current branch and the option to include uncommitted changes](https://onevium.com/assets/docs/worktrees/en/worktrees-01-start-point.png "Figure 1: Enable Worktree on the right, then choose a starting point on the left. Real 1.2.4 development components with sample project data; no task has been sent.") For a first try, send: ```text Check the working directory and Git branch. List the included repositories. Tell me which copy this task will edit. Do not edit any files yet. ``` Continuing this conversation reuses its worktree; each message does not create another one. Onevium remembers the project's Worktree setting, so check it when starting your next conversation. ## 2. Include repositories inside the project Suppose your project folder contains two independent Git repositories: `app` and `website`. 1. Enable Worktree, then click **Start from** or **Choose repositories**. 2. Under **Repositories**, select the ones this task needs (Figure 2). Select only `website` for a website change, or both for work across the application and website. 3. Under **Start point**, click each repository to choose its starting branch. Including uncommitted changes is also a separate choice for each repository. ![The repository menu has app and website selected, with app starting from main and website starting from develop](https://onevium.com/assets/docs/worktrees/en/worktrees-02-repositories.png "Figure 2: Select repositories above, then set their starting points below. The same development UI demo uses sample app and website repositories.") Onevium creates a worktree for each selected repository, preserving its relative location in the new directory. The repositories remain independent: commit and merge each separately. | Project structure | What gets created | | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | The project root is a Git repository | The root repository is always included; independent nested repositories are added when selected | | The project root is an ordinary folder containing repositories | Select at least one repository; a sole repository is selected automatically. Ordinary files in the original folder are not copied wholesale | | A nested repository is not selected | It stays out of the new worktree; its original directory remains in place | Independent nested repositories are different from Git submodules, which are not checked out automatically. If a repository you need is missing from the list, open that repository's directory as a project directly. ## 3. Check the result and keep your changes Once preparation finishes, the conversation shows **Worktree · branch name**. Verify the actual path and branch in the conversation before editing. Use [Files, terminal, and Review](https://onevium.com/docs/files-terminal-review) to inspect file changes. **Finishing the task does not merge changes into the original branch.** Review the diff and run the project's checks, then explicitly ask the assistant to commit and merge into your chosen target branch. Handle each repository separately. To compare two approaches, start two separate worktree conversations. Continuing or adding a conversation inside an existing worktree shares that copy of the files. Split view does not create additional isolation. ## 4. Clean up and restore 1. Open **Settings → Worktrees → General**. Find the target under **Managed worktrees**, make sure your work is kept, then click **Delete** (Figure 3). Automatic cleanup only removes older worktrees without unsaved changes. ![General worktree settings with automatic cleanup options and the Delete button beside a managed worktree](https://onevium.com/assets/docs/worktrees/en/worktrees-03-manage.jpg "Figure 3: Click Delete beside the target worktree. Real development UI components with sample project data and paths.") 2. Read the confirmation dialog (Figure 4). If there are unsaved changes, confirm that a snapshot can be created. If it cannot, cancel and keep your files first. Manual deletion also archives linked conversations. ![The deletion dialog explains snapshots, branch retention, conversation archiving, and the exclusion of Git-ignored files](https://onevium.com/assets/docs/worktrees/en/worktrees-04-delete.jpg "Figure 4: Check the snapshot and archiving information before deleting. This demo only opens the confirmation dialog; nothing was deleted.") **Git-ignored local configuration, such as `.env.local`, is not included in snapshots; keep it separately.** 3. To recover the worktree, open its original conversation, click **Restore worktree** (Figure 5), and wait for setup to finish. If the conversation is archived, first go to **Settings → Archived sessions** and click **Restore**, then open it. ![The Worktree cleaned up notice in a conversation, with the Restore worktree button on the right](https://onevium.com/assets/docs/worktrees/en/worktrees-05-restore.jpg "Figure 5: Click Restore worktree in the original conversation. The same development UI demo uses a sample path.") Deleting or restoring a worktree does not merge its code. ## Troubleshooting | Symptom | What to do | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No Worktree switch | Check that Git is available and the project is, or contains, a Git repository; an empty folder alone is not enough | | Edits from the original directory are missing | Start from the current branch and select Include uncommitted local changes when creating the worktree; an existing worktree does not sync live with the original | | Dependencies or `.env` configuration are missing | Install dependencies in the new directory using the project instructions. List needed Git-ignored configuration in `.worktreeinclude` at the relevant repository root to copy it into newly created worktrees | | The environment script fails | Click View log in the creation progress and fix the reported environment issue; a created directory does not prove the project can run |