Worktrees

A git worktree is a second (third, fourth…) working directory attached to the same repository, each with its own branch checked out. Instead of stashing and switching branches in one folder, you keep feature/checkout-flow in one directory and fix/login-crash in another — simultaneously. For agentic coding this is a superpower: each worktree opens as its own Nx IDE window with its own Nexgile Code session, so you can run an agent task per branch, in parallel, without the tasks stepping on each other’s files. Nexgile Code builds worktree management directly into the product so you never have to touch git worktree on the command line.

The Worktrees view

Open Settings → Worktrees. The view lists every worktree of the current repository — branch name, directory path, and badges: Primary marks the main checkout, Locked flags worktrees git has locked (hover for the reason), and detached-HEAD checkouts are labeled as such. The list refreshes automatically.

Requirements: the workspace must be a git repository, opened as a single folder at the repository root. Multi-root workspaces and subfolder checkouts aren’t supported — the view tells you (and shows the git root path to open) if that’s the case.

Creating a worktree

Click Create worktree. The Create Worktree dialog offers:

• Create new branch — name the branch and pick a From base branch (searchable list of local and remote branches), or
• Checkout existing branch — pick any branch not already checked out elsewhere,

plus the target directory (a sensible location under ~/.nexgile/worktrees/ is suggested; Select Worktree Location lets you choose your own). Click Create and the worktree is ready in seconds — plus file-copying time, if you use the include file described next.

.worktreeinclude: carrying local files across

A fresh worktree contains only the files tracked on its branch — no .env, no node_modules, none of your untracked local state. If you want those copied into each new worktree, list them (gitignore-style patterns) in a .worktreeinclude file at the repository root.

The Worktrees view shows the status at the bottom: “.worktreeinclude file found — files will be copied to new worktrees”, or a Create from .gitignore button that generates a starting version from your .gitignore (a good approximation, since the local files you want to carry are usually exactly the ones you don’t commit) and opens it for editing.

Tip

Including node_modules saves an install step per worktree but makes creation noticeably slower on big projects — you’ll see a “Copying files…” progress indicator. Including just .env and running the package install per worktree is often the better trade.

Switching — and the auto-opening panel

Two ways to move between worktrees:

• Click a worktree row — switches the current window to that directory (the window reloads).
• Open in new window (the arrow icon) — opens the worktree in a separate Nx IDE window, leaving your current one untouched. This is the one you’ll use for parallel work.

Either way, when the target window comes up, Nx IDE automatically opens the Nexgile Code panel in it — you land ready to start a task, not hunting for the sidebar icon.

The home-screen selector

Enable Show worktrees in home screen (a toggle in the Worktrees view, backed by the showWorktreesInHomeScreen setting) and — whenever the repo has more than one worktree — a worktree switcher appears on the chat home screen: see which worktree you’re in, jump to another, create a new one, or hit Manage Worktrees to open the full view.

Parallel-branch workflows

The pattern that makes worktrees worth it:

1. Create a worktree per stream of work — feature/api-v2, fix/flaky-tests — each Open in new window.
2. Start an agent task in each window. Every window is a fully independent Nexgile Code session: its own conversation, its own checkpoints, its own terminal working directory, all scoped to that worktree’s files.
3. Approve and steer each task as it needs you — one agent’s edits can never collide with another’s, because they’re in different directories on different branches.
4. Merge branches through your normal git flow when each stream lands.

This is the manual, always-available counterpart to Workflow Mode’s automated pipeline: you parallelize across branches; each branch still gets a focused, isolated agent.

Deleting a worktree

The trash icon (disabled for the Primary worktree and the one you’re currently in) opens a confirmation dialog. Read it — deletion is destructive and cannot be undone. It removes:

• the branch, including any uncommitted changes, and
• all files in the worktree directory.

Large worktrees take a moment to remove. Locked worktrees require ticking Force delete.

Caution

Deleting a worktree is not “closing a window” — it deletes the branch. Push or merge anything you care about first.

Practical guidance & caveats

• One branch, one worktree. Git only allows a branch to be checked out in a single worktree at a time; already-checked-out branches can’t be selected for a new one.
• Disk usage is real. Each worktree is a full working copy (plus whatever .worktreeinclude copies). Prune worktrees you’re done with.
• Services and ports. Two worktrees running the same dev server will fight over the port — vary the port per worktree or run one at a time.
• Keep an eye on cost. Parallel agent sessions consume tokens in parallel too; per-task cost caps (Command Guardrails & Limits) apply per session.

Troubleshooting

Symptom	Cause & fix
View says the workspace is not a git repository	Worktrees require git — open a folder with a repository
“Worktrees are not supported in multi-root workspaces”	Open a single folder instead of a multi-root workspace
“This workspace is a subfolder of a Git repository”	Open the repository root (the view shows you the git root path)
A branch can’t be selected when creating	It’s already checked out in another worktree — every branch lives in at most one
Delete fails on a locked worktree	Tick Force delete in the delete dialog
No worktree switcher on the home screen	It appears only with Show worktrees in home screen enabled and more than one worktree present

Related

• Workflow Mode — automated implement → test → review → ship on one branch
• Checkpoints — per-workspace undo for agent changes
• Subtasks & Todo Lists — splitting work within a single session
• Working with Large Projects — when to parallelize vs. split into sequential tasks