Worktrees

What it's for

A worktree is another working folder of the same Git repository, tied to a different branch. The files are separate; the history is the same. When two agents need to edit the same project at the same time, each one gets its own folder, and one agent's changes do not show up by accident in the other's git status. PrumoGrid creates the worktree from New stage, shows each one on the project card and offers Remove when you are done.

When to use it and when not to

Use a worktree when there are two simultaneous jobs in the same repository. For example: in loja-api, one agent fixes the PRIMEIRA coupon while another updates the documentation. It also works for an experiment you may throw away entirely.

Do not use one when the stages happen one after another in the same terminal; the project folder is enough for that. It also does not apply to projects without Git: in an SVN project, the option appears disabled with the reason, and the stage runs in the project folder. And keep in mind that a worktree starts with no dependencies installed. If the project needs npm install and a .env to run the tests, plan for that setup.

Step by step

Create a worktree from New stage

The example creates the cupom-fix worktree in loja-api for a Codex stage.

1. Select loja-api and click New stage.
2. In What needs to be done?, write the task, for example Fix the PRIMEIRA coupon, which gives a double discount with two items in the cart, and add a test.
3. In Runs on, choose the agent.
4. Open More options and then Stage options. In Folder, choose In a new worktree.
5. In the worktree name (becomes the branch) field, type cupom-fix. The note below reminds you that the worktree isolates the task on its own branch and starts with no dependencies installed.
6. Check the plan: it shows the name, the branch and the path, such as New worktree "cupom-fix" (branch cupom-fix) at: C:\demo\.tg-worktrees\loja-api-cupom-fix.
7. Click Create stage. A Windows confirmation, Create worktree, shows the repository, the new folder and the new branch based on the current branch. Confirm with Create.
8. The notice says that the stage was created in the new worktree and which pane was opened. The terminal starts inside the worktree folder.

The .tg-worktrees folder sits next to the repository, outside it. In the example, C:\demo\.tg-worktrees, next to C:\demo\loja-api. That way the worktree does not show up in the main folder's git status.

The name accepts letters, digits, dot, hyphen and underscore, starting with a letter or digit, up to 64 characters. It cannot contain .., end in . or .lock, or be a reserved Windows name such as con or nul.

Check from the terminal

In a PowerShell in the main folder, these commands only read:

git worktree list
git -C ..\.tg-worktrees\loja-api-cupom-fix status --short

The first lists the main folder and the worktree with the cupom-fix branch. The second shows only what changed inside the worktree.

What you see on screen

Enlarge screenshot ↗

The project card shows at most four worktree lines, in this order: the main branch, then the worktrees with an open session and, after those, the ones PrumoGrid created in .tg-worktrees. Those beyond four, and the ones created by other tools, are collapsed into one line.

Collapsing the other N worktrees line does not delete folders or Git records; it only hides the lines.

Remove a worktree

1. On the project card, hover over the worktree's line. The × tooltip says which folder will be removed and reminds you that the branch stays in the repository.
2. Click the ×. The Remove worktree confirmation shows the folder, the branch and whether there are uncommitted changes.
3. With no changes, it says There are no uncommitted changes. Confirm with Remove.
4. With changes, it warns that removing now discards that work and shows a checkbox such as Yes, discard the 2 uncommitted changes. Without checking the box, the removal is refused and nothing is discarded.
5. If PrumoGrid cannot check for changes, the checkbox says Yes, remove even without being able to check for changes. Prefer to check with git status --short in the folder before you tick it.

The confirmation is a native Windows dialog, with the Remove and Cancel buttons. For a worktree with no changes, it looks like this:

Remove worktree
Remove worktree "C:/demo/.tg-worktrees/loja-api-cupom-fix"?
Branch: cupom-fix
There are no uncommitted changes.
The branch stays in the repository; only the worktree folder goes.

After the removal, the notice says that the worktree was removed and that the branch stays in the repository. The folder is gone from disk. The cupom-fix branch stays, with whatever commits it has. If you no longer need it after the merge, delete it with git branch -d cupom-fix.

On a missing line, Remove deletes only the Git record, because the folder no longer existed.

Cleanup

Worktrees pile up. Each stage with In a new worktree creates a folder, and closing the project removes none of them. Every so often:

• Look at the card's lines and the other N worktrees line.
• Commit or discard what was left in each worktree and remove it with the ×.
• Run git worktree list to check what is left. For records of folders that were already deleted by hand, git worktree prune cleans up Git.

Tips

• Clicking a worktree's line on the card takes you to its terminal. If there is no terminal open there, it opens a new one in that folder.
• Use short, neutral names that say what the task is: cupom-fix, docs-readme. The name becomes the branch and appears on the card.
• If a stage in the worktree will run a verification such as npm test, set up the dependencies in that worktree first. The verification runs in the stage's folder.
• Handoff files between agents, such as ANALISE.md, stay in the folder of whoever wrote them. If the next agent works in another folder, give the full path in the instruction.
• The change review shows the state of the folder it names. Confirm that it is the right worktree before committing.

Known limitations

• Worktrees depend on Git. In SVN, the isolated copy is not offered.
• PrumoGrid does not copy node_modules or .env, and runs nothing when it creates one: only the worktree folder is created.
• Remove does not delete the branch.
• Closing a project in the catalog does not remove its worktrees from disk.
• The card shows up to four lines; the rest go into other N worktrees.