@niroai/niro 0.3.1 → 0.3.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +23 -3
- package/docs/working-on-branches.md +65 -102
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -12,9 +12,29 @@ One package gives you three things:
|
|
|
12
12
|
|
|
13
13
|
> **Two ways to do everything:** every task below shows the **terminal** command *and* how you'd **ask the agent**. Pick whichever you prefer — they call the same code.
|
|
14
14
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
15
|
+
## Working on branches
|
|
16
|
+
|
|
17
|
+
Your projects cover the repos and branches you chose to index. On every question, Niro routes
|
|
18
|
+
to the project matching your repo and current branch. When you are on a branch **no project
|
|
19
|
+
covers** (with real changes), Niro refuses to answer from stale code. Your assistant offers the fix:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
niro new-temp-project # run once in the repo folder
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
This creates your own private copy of the project that follows your branch and your
|
|
26
|
+
uncommitted edits, live (keep `niro watch` running). Teammates are not affected and cannot
|
|
27
|
+
see your copy. Switching branches needs nothing: Niro answers from your copy on the new
|
|
28
|
+
branch, and from the matching indexed project on branches you already cover. When your branch
|
|
29
|
+
is merged:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
niro discard-temp-project
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
If you forget, idle copies are cleaned up automatically after two weeks. Full guide:
|
|
36
|
+
[docs/working-on-branches.md](https://unpkg.com/@niroai/niro/docs/working-on-branches.md)
|
|
37
|
+
(plain-text file, ships inside the package too).
|
|
18
38
|
|
|
19
39
|
---
|
|
20
40
|
|
|
@@ -1,135 +1,98 @@
|
|
|
1
|
-
# Working on branches
|
|
1
|
+
# Working on branches with Niro
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
Your team decides what Niro indexes: you create projects, and each project
|
|
4
|
+
covers the repos and branches you choose. One project might index main,
|
|
5
|
+
another might index a develop or release branch. That is up to you.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
When you ask a question, Niro picks the project that matches your repo and
|
|
8
|
+
the branch you are currently on. This page is about the moment when NO
|
|
9
|
+
project matches: you created a new branch and changed code that no project
|
|
10
|
+
has indexed yet. Two minutes to read.
|
|
8
11
|
|
|
9
|
-
|
|
10
|
-
Codex, or anything else that speaks MCP) and wherever your git repositories live (GitHub, GitLab,
|
|
11
|
-
Bitbucket, or a self-hosted git server). Niro only needs two things: your repository's git URL and
|
|
12
|
-
the branch you're on.
|
|
12
|
+
## The short version
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
There is one command to remember:
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
niro new-temp-project
|
|
17
17
|
|
|
18
|
-
|
|
19
|
-
> **temporary project** — a private copy that follows your branch and your edits live — and from
|
|
20
|
-
> then on, answers come from *your* code, not the team's.
|
|
18
|
+
Run it in your repo folder when Niro asks for it. That is all.
|
|
21
19
|
|
|
22
|
-
|
|
20
|
+
## What you will see
|
|
23
21
|
|
|
24
|
-
|
|
22
|
+
You create a branch that no project covers and start changing code.
|
|
23
|
+
Then you ask your AI assistant something about the code.
|
|
25
24
|
|
|
26
|
-
Niro
|
|
27
|
-
|
|
25
|
+
Niro notices that no project has indexed this branch. Instead of giving
|
|
26
|
+
you a wrong answer based on some other branch, it replies with something
|
|
27
|
+
like:
|
|
28
28
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
| On the indexed branch (e.g. `main`), no edits | Answers from the shared team index. Business as usual. |
|
|
32
|
-
| Just created a new branch, no changes yet | Still answers from the team index — your code is *identical* to what's indexed, so the answers are provably correct. No friction for a fresh branch. |
|
|
33
|
-
| On a branch with real changes, **with** a temporary project | Answers from **your temporary project** — your branch, your uncommitted edits, live. |
|
|
34
|
-
| On a branch with real changes, **no** temporary project | **Refuses to answer** and tells your assistant what to do about it (see below). |
|
|
29
|
+
I cannot answer this safely. Your branch has diverged
|
|
30
|
+
from the branch Niro indexed.
|
|
35
31
|
|
|
36
|
-
|
|
37
|
-
branch *looks* right and is quietly wrong — wrong line numbers, missing methods, dead code that
|
|
38
|
-
you already deleted. Niro treats that as worse than no answer.
|
|
32
|
+
Your assistant will offer to fix this by running:
|
|
39
33
|
|
|
40
|
-
|
|
34
|
+
niro new-temp-project
|
|
41
35
|
|
|
42
|
-
|
|
36
|
+
Say yes, or run it yourself in the repo folder. It takes a few seconds.
|
|
43
37
|
|
|
44
|
-
|
|
45
|
-
folder. One command; takes seconds.
|
|
46
|
-
2. **Answer from the team index anyway** — only if *you* explicitly say so. The answer will carry
|
|
47
|
-
a visible label saying it describes the indexed branch, not your code.
|
|
48
|
-
3. **Skip Niro for this question** — the assistant falls back to reading files directly.
|
|
38
|
+
## What the command does
|
|
49
39
|
|
|
50
|
-
|
|
51
|
-
you've allowed that.
|
|
40
|
+
It creates your own private copy of the project inside Niro.
|
|
52
41
|
|
|
53
|
-
|
|
42
|
+
- The copy follows your branch, including changes you have not committed.
|
|
43
|
+
- Every save updates the copy, as long as "niro watch" is running.
|
|
44
|
+
- Teammates are not affected. They keep using the shared project.
|
|
45
|
+
- Nobody can see your copy. Not even teammates on your account.
|
|
54
46
|
|
|
55
|
-
|
|
47
|
+
From then on, answers come from YOUR code.
|
|
56
48
|
|
|
57
|
-
|
|
58
|
-
teammates on the same account. Your half-finished code stays yours.
|
|
59
|
-
- **Live.** Your working tree — including uncommitted edits — is uploaded once, and every save
|
|
60
|
-
after that streams in automatically (while `niro watch` is running). Ask a question seconds
|
|
61
|
-
after saving; the answer reflects the save.
|
|
62
|
-
- **Cheap.** Creating one copies the already-computed index. No re-parsing of the whole project,
|
|
63
|
-
no waiting for a full rebuild.
|
|
64
|
-
- **Branch-aware, automatically.** Once your temporary project exists, you never point anything at
|
|
65
|
-
it. Niro routes each question by the branch you're on: feature branch → your copy; switch back
|
|
66
|
-
to `main` → the team index. Switch back and forth all day; it just follows.
|
|
49
|
+
## Switching branches
|
|
67
50
|
|
|
68
|
-
|
|
51
|
+
Nothing to do. Niro checks which branch you are on for every question.
|
|
69
52
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
service A?") reflect *all* of your local work at once. Each repo can even be on a different
|
|
74
|
-
branch — Niro mirrors whatever your working folders actually look like.
|
|
53
|
+
- On your new branch: answers come from your private copy.
|
|
54
|
+
- On a branch one of your projects already indexes: answers come
|
|
55
|
+
from that project.
|
|
75
56
|
|
|
76
|
-
|
|
57
|
+
## When your work is merged
|
|
77
58
|
|
|
78
|
-
|
|
59
|
+
Run this in the repo folder:
|
|
79
60
|
|
|
80
|
-
|
|
81
|
-
the temporary project has served its purpose — discard it with `niro discard-temp-project`. The
|
|
82
|
-
shared index picks up your merged commits through its normal syncing; nothing else to do.
|
|
61
|
+
niro discard-temp-project
|
|
83
62
|
|
|
84
|
-
|
|
63
|
+
It deletes your private copy. Your local files are never touched.
|
|
64
|
+
If you forget, Niro deletes unused copies by itself after two weeks.
|
|
85
65
|
|
|
86
|
-
|
|
87
|
-
that's mid-feature, both Niro and the CLI warn before deleting it and ask you to confirm.
|
|
88
|
-
- **Forgot to discard?** Idle temporary projects (no edits for N days — 14 by default, and your
|
|
89
|
-
admin can change it per account or per project) are cleaned up automatically. Only the copy is
|
|
90
|
-
deleted; your local code is never touched, and a fresh copy is one command away.
|
|
66
|
+
## A feature that spans several repos
|
|
91
67
|
|
|
92
|
-
|
|
68
|
+
Run "niro new-temp-project" in each repo folder you branch.
|
|
69
|
+
All of them join the same private copy, so questions that cross repos
|
|
70
|
+
(for example: what breaks in service B if I change service A?) see all
|
|
71
|
+
of your changes together.
|
|
93
72
|
|
|
94
|
-
|
|
95
|
-
Niro project this folder belongs to. It's useful when one repository is part of several Niro
|
|
96
|
-
projects, or when you start your assistant from a parent folder that isn't itself a repository.
|
|
73
|
+
## Common questions
|
|
97
74
|
|
|
98
|
-
|
|
75
|
+
Can teammates see my unfinished code?
|
|
76
|
+
No. Your copy is private to you.
|
|
99
77
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
-
|
|
104
|
-
resolves by itself.
|
|
78
|
+
Does this work with my AI assistant and my git host?
|
|
79
|
+
Yes. Any assistant that supports MCP (Claude Code, Cursor, Windsurf,
|
|
80
|
+
Codex, and others) and any git server (GitHub, GitLab, Bitbucket,
|
|
81
|
+
self-hosted).
|
|
105
82
|
|
|
106
|
-
|
|
83
|
+
Is creating a copy slow?
|
|
84
|
+
No. Niro copies the existing index instead of re-reading your code.
|
|
85
|
+
It normally takes seconds.
|
|
107
86
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
niro discard-temp-project # after merging: delete the copy; routing falls back by itself
|
|
112
|
-
niro discard-temp-project --project <id> # discard from another machine / lost local state
|
|
113
|
-
```
|
|
87
|
+
I just created a branch and have not changed anything. Will Niro nag me?
|
|
88
|
+
No. Your code is still identical to the branch you started from, so Niro
|
|
89
|
+
answers normally. It only steps in once your code actually differs.
|
|
114
90
|
|
|
115
|
-
|
|
91
|
+
We already have projects for main and develop. Do I need this?
|
|
92
|
+
Not while you are on main or develop: Niro routes to the matching project
|
|
93
|
+
by itself. You only need a temporary project for a branch that none of
|
|
94
|
+
your projects cover.
|
|
116
95
|
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
branch, without you asking.
|
|
121
|
-
|
|
122
|
-
## Requirements and honest limits
|
|
123
|
-
|
|
124
|
-
- **Git is required** for branch detection. Folders that aren't git repositories can still be
|
|
125
|
-
indexed and queried (uploaded as plain folders), but there are no branches to follow — the
|
|
126
|
-
branch logic on this page doesn't apply to them.
|
|
127
|
-
- **Any git host works.** Matching uses the repository URL and branch name only — nothing
|
|
128
|
-
GitHub-specific. HTTPS and SSH remotes both work.
|
|
129
|
-
- **Your backend must support routing.** If the server is older than this feature, the CLI warns
|
|
130
|
-
you loudly at `new-temp-project` time instead of letting answers silently come from the wrong
|
|
131
|
-
place.
|
|
132
|
-
- **Detached HEAD** (bisecting, checking out a tag): there's no branch to follow, so Niro answers
|
|
133
|
-
from the team index with an advisory note rather than refusing.
|
|
134
|
-
- **A brand-new repo** created mid-feature (not yet in any Niro project) can't join a temporary
|
|
135
|
-
project yet — Niro will say so honestly instead of pretending to know it.
|
|
96
|
+
What if I really want an answer from the shared project while on my branch?
|
|
97
|
+
Tell your assistant so. The answer will be clearly labeled as describing
|
|
98
|
+
the indexed branch, not your code.
|