How it works is in Worktrees and branches. This page answers the messages you may see.

"This folder is now on <branch>, which niro-local has not indexed."

You switched to a branch with no graph yet. If the repository is indexed on another branch, Niro makes a temporary copy and builds it. Otherwise it offers to index the folder.

"this folder's index was copied from project P and has not been built from this folder's files yet"

Answers come from a copy of the main project's graph until this folder's own build finishes. That takes moments for small changes.

"A project's folders must all be on one branch."

A project's folders must all be on the same branch. Put them on one branch. Or add the folder to a different project with niro init --project <name>.

"This folder is on no named branch"

You have a commit checked out directly (a detached HEAD). Niro answers from the folder's last used graph, and names its branch.

I switched back to my old branch. Is its graph still there?

Yes. Niro keeps one graph per folder and per branch, and switches without rebuilding. Each answer then carries one line saying which project it came from.

A new git worktree was built by itself, but an older one was not.

The watcher builds worktrees it sees appear. Worktrees that existed before Niro first saw the repository are only noted. Build one with niro build in its folder.

"Gave up building <folder> after N tries; run niro build there to see why."

The watcher tried three times, waiting 2 and then 10 minutes in between. Run niro build in that folder to see the error.

When are temporary projects deleted?

After 14 days with no build and no question. They are kept while a build runs, while a folder of them is on that branch, or while a folder of them is missing. Change the 14 days with NIRO_LOCAL_BRANCH_INDEX_IDLE_DAYS.

A folder that came back still shows its old "missing since" date.

Known. The first date it went missing is kept.

The same file has two names in two worktrees.

Known problem.

My folder is not in git. How does it get a branch?

Give one when you add it: niro init --branch <name>. For a folder in git, the branch is read from git, and --branch is ignored.

Folders on different branches ended up in one project.

Known problem for folders added without a branch (outside git).

My folder holds several repositories on different branches.

Niro treats such a folder as having mixed branches. Add the repositories one by one if you need each on its own branch.

"<path> is now on X; its part of this answer describes Y"

Another folder of this project switched branch since its last build. That part of the answer is about the old branch until it is rebuilt.