gitnexus-refactoring

Refactoring with GitNexus

When to Use

• "Rename this function safely"
• "Extract this into a module"
• "Split this service"
• "Move this to a new file"
• Any task involving renaming, extracting, splitting, or restructuring code

Bind the repository first

Refactoring writes to disk. rename with dry_run: false edits files in whichever repository was resolved, so binding identity here is a safety gate, not bookkeeping.

Call list_repos {} before the first tool call. With one indexed repository, use the examples below as written. With more than one, pass repo on every call: an omitted repo normally errors, but under an MCP policy with a configured default it resolves to that default silently. If you cannot tell which repository is meant, stop and ask. Never run rename with dry_run: false until the preview in the same bound repository has been reviewed — its returned file_path values show which checkout is about to be written, so read them as a confirmation of identity.

list_repos is paginated, so page with offset: pagination.nextOffset until hasMore is false before concluding a repository is absent.

detect_changes takes worktree when you are editing a linked worktree the MCP server was not launched from; otherwise git diff runs in the wrong checkout and reports nothing changed, which reads as a verified refactor.

Workflow

0. list_repos {}                                  → Bind repo (and worktree)
1. impact({target: "X", direction: "upstream"})  → Map all dependents
2. query({search_query: "X"})                            → Find execution flows involving X
3. context({name: "X"})                           → See all incoming/outgoing refs
4. Plan update order: interfaces → implementations → callers → tests

If "Index is stale" → run node .gitnexus/run.cjs analyze in terminal. Hot-tool staleness names which index answered (branch/lastCommit) and how fresh it is (status). Re-analyze only for behind or diverged — current is identity, unknown is unmeasurable.

Checklists

Rename Symbol

- [ ] list_repos {} — bind repo; explicit repo when >1 indexed, ask if ambiguous

Extract Module

Split Function/Service

Tools

rename — automated multi-file rename:

impact — map all dependents first:

detect_changes — verify your changes after refactoring:

partial: true (a graph query failed) or truncated: true (the changed-symbol listing was capped) means the result is short of the truth: a short or empty list is not proof that only the expected files changed. Re-run it rather than treat the refactor as verified.

A wrong-worktree zero carries neither flag and is indistinguishable from a clean verification, so confirm the diffed checkout is the one you edited.

cypher — custom reference queries:

Risk Rules

Example: Rename validateUser to authenticateUser

With a single indexed repository, step 0 returns total: 1 and the repo argument drops out of every call above.