magus-refs
List where an ingested code symbol is defined and referenced
Synopsis
magus refs <symbol> [flags]
Description
List where an ingested code symbol is defined and every file that references it, as file:line rows drawn from the SCIP index.
This is the occurrence-shaped view a symbol's fan-in needs: a flat list, which is what you want when the question is "who calls this". The node-link neighborhood that magus query renders is the wrong shape for that question, which is why this is its own command rather than a flag.
The argument is a symbol node ID (symbol:...) or a name that resolves to one. Symbols come from a declared SCIP index; see knowledge.symbols in the configuration. A workspace with no index has no symbols to report, and says so rather than falling back to a text search - a grep result and an index result answer different questions, and quietly substituting one for the other is how a wrong answer looks right.
--definition answers "where is the body" with the exact lines: each definition as path:start-end, from the index's enclosing range, checked against the file on disk: verified when the file predates its index, changed (exit 1) when the symbol's name has left the start line, and unverified when the name is there but the file was edited since. An index that recorded no end line says so instead of guessing one. --source adds the lines themselves.
--text switches to that other question on purpose: a literal substring search with no symbol index and no graph, printed as path:line:text like every other grep-shaped tool. It is the replacement a guard deny routes a recursive grep to, so it answers on a cold worktree with no index built. Its exit code is grep's (0 matched, 1 no match, 2 error), not the verdict codes the symbol lookup above uses - the two modes answer different questions and are not meant to share a contract.
Options
- --definition
- Print each definition as path:start-end, the lines its body spans, checked against the file on disk. A range the index did not record is said, never guessed
- --limit | head
- Print at most this many --text matches, then say how many more there were (0 for all). What `| head` would do, without losing the count or the exit code
- --no-generated string
- In the fallback text search shown beside a symbol miss, or with --text, exclude declared-output files entirely instead of searching them and marking the ones that match
- --occurrences
- Every exact source range, uncapped and verified against the tree - the view a mechanical edit needs, where the default line list is capped and describes fan-in
- --refresh
- Re-ingest the SCIP index before answering
- --source
- With --definition (implied), also print the definition's lines: a symbol's body by name, in place of grep -n then sed -n
- --text
- Raw substring search, no symbol index: print path:line:text matches and exit 0/1/2 for matched/no-match/error (grep's contract, not refs' verdict exit codes). Trailing paths scope the search, as grep's do; without any it searches the workspace
Examples
Every reference to a symbol
magus refs Open
By fully-qualified node ID
magus refs symbol:github.com/egladman/magus/Open
As JSON
magus refs Open -o json
Where a symbol's body starts and ends
magus refs Open --definition
A symbol's body, by name
magus refs Open --source
Raw text search, no index needed
magus refs TODO --text
See Also
magus(1), magus-ls(1), magus-describe(1), magus-run(1), magus-x(1), magus-where(1), magus-affected(1), magus-graph(1), magus-query(1), magus-explain(1), magus-path(1), magus-watch(1), magus-events(1), magus-status(1), magus-clean(1), magus-shell(1), magus-vcs(1), magus-queue(1), magus-doctor(1), magus-config(1), magus-session(1), magus-memory(1), magus-job(1), magus-notes(1), magus-diff(1), magus-server(1), magus-broker(1), magus-mcp(1), magus-buzz(1), magus-completion(1), magus-man(1), magus-init(1), magus-spell(1), magus-agent(1), magus-self(1), magus-version(1)