Worktrees and branches
Niro keeps one graph per folder and per branch. When you switch branch, Niro answers from that branch's graph. A git worktree is a second folder checked out from the same repository. When you open a new worktree, Niro builds it too.
How Niro knows your branch
Niro reads the file .git/HEAD in the folder. It never runs git.
- Detached HEAD. If you are not on a named branch, Niro answers from the folder's last used graph, and says so.
- No git. A folder outside git has no branch. Give it one when you add it:
niro init --branch <name>.
Switching branch
- To a branch Niro has seen before. Niro switches to that branch's graph. Each answer then carries one line saying which project and build it came from.
- To a new branch of a repository Niro already indexes. Niro makes a temporary project for it. It copies only this folder's graph from the main project, so the first answers are quick, and then builds the folder from its own files. Until that build is done, answers carry a note saying the graph was copied and not yet built.
- It is named after the project and the branch, for example
shop-feature-login. - Your settings for the folder are copied with it: route rules, environment values and base address.
- It is named after the project and the branch, for example
- All folders of one project must be on one branch. If they are not, Niro says "A project's folders must all be on one branch".
New worktrees
The background watcher builds a new worktree of a repository Niro already indexes. Worktrees that already existed when Niro first saw the repository are noted, but not built. Build one of those with niro build in its folder.
If a worktree's build fails, the watcher tries again after 2 minutes and after 10 minutes. After 3 tries it stops, and logs "Gave up building <folder> after N tries; run niro build there to see why."
Which folder an agent's questions are about
Niro's tools answer for the folder the agent's session started in. If you work in another folder (another worktree, or another service), two things help:
- run
niro statusthere to see whether it is indexed; - run
niro build <folder>after editing it.
Clean-up
Niro removes old copies by itself. It does this at the end of a build, never while answering a question:
- A temporary project is removed after 14 days with no build and no question. It is kept while a build is running, while one of its folders is on that branch, or while a folder of it is missing.
- The graph of a folder deleted from disk is removed 14 days after Niro first saw it missing.
- To remove missing folders now, run
niro clean.
Change the 14 days with NIRO_LOCAL_BRANCH_INDEX_IDLE_DAYS and NIRO_LOCAL_MISSING_FOLDER_DAYS. Set either to 0 to turn that clean-up off.