# 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.

- **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 status` there 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.