gs
Explore a file's shape and neighbors: symbols with callers, imports, reverse importers, co-changed files, and related files sharing tokens. Answers 'who uses this file' without reading code.
Instructions
Drill into a known file. Returns these sections as compact text:
Symbols — top-level + per-class methods (name, kind, line range, extends/implements). With cross-file callers attached per exported symbol (inline if 1 caller; newline-per-caller block if ≥2). For huge files (>20 symbols, no
match), symbols are reordered by caller count (most-used first) and truncated to top 15.Imports — 1-hop internal outbound dependencies (library imports stripped).
Importers — 1-hop reverse: files in this repo that import this one. With
match, additionally lists EVERY indexed file (importer or not, any language) whose CONTENT references the matched term even when its filename does not (a registry, admin, or config file using the symbol — or a frontend file referencing a backend name). That subsection IS the complete "who uses " answer: it is exhaustive over indexed content, so a subsystem absent from it does NOT use the symbol — do not grep to enumerate or re-verify use-sites, and do not keep hunting in subsystems the section rules out.Edited together — files that keep changing in the SAME COMMITS as this one, from git history, shown with the count as evidence ("changed together in 14 of this file's 17 commits"). This is a HABIT, not a dependency: no import or call edge connects them, so do not go looking for one. It is frequently what an edit here forgets — a sibling implementation with a shared interface, a test in another language, a doc or template that has to stay in sync. Files connected to this one by an import edge are omitted here, so everything shown is a file the graph did NOT give you. Rendered in EVERY view, including a narrowed one. Absent = no git history yet (a new file, a shallow clone) or nothing pairs strongly enough.
Related — files sharing rare identifier/string-literal tokens with this file (with
match: with the matched symbols' code region), shown only when NO import edge connects them. These are name-reference relations the import graph cannot see — Django migrations↔models, config-by-name registration, cross-language (JS↔Python) pairs. Treat them as first-class neighbors: the shared token shown is the reason they are related. Rendered in EVERY view, including a narrowed one. Use this AFTER find surfaces a candidate file. This is the right tool for "who uses this file" / "who calls this symbol" — no separate call needed.
view controls which sections you get (default full = all of them). symbols, imports, importers, callers each return one section in isolation when you want a byte-light answer.
For god-files (large classes, large routers, large config modules), pass match to filter symbols/imports/importers/callers to one area — e.g. match: "auth" or match: "/^handle/". Substring is case-insensitive; wrap in slashes for regex.
Prefer this over Read when you need shape, neighbors, or usage. Reach for Read only for implementation details inside a method body. If you have called gs on 5+ files for one question, you are enumerating — go back to find with a sharper path glob or a different concept token instead.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| view | No | Which sections to return. Default "full" = symbols (with inline callers) + imports + importers. Use one of the narrower views to halve or quarter the output when you know what you need: "symbols" (shape only, no callers), "imports" (outbound only), "importers" (inbound only), "callers" (per-symbol cross-file callers in expanded form, no symbol shape). | |
| match | No | Filter all sections by name. Substring (case-insensitive) by default; use `|` to OR substrings (`match: "resource|tile"`); wrap in slashes for regex (`match: "/^handle/"`). Use this on large/god-files to avoid a wall of output — e.g. `match: "tile"` on a big models.py reduces output to just tile-related symbols, their callers, and matching imports/importers. | |
| symbol | No | Deliver the BODY of the named symbol(s) inline, sliced from their indexed line range — so you read a method WITHOUT a Read at a guessed offset. Comma/pipe-separate names (`serialize,restore_state`). A bare name matches the method (`serialize` → `Graph.serialize`). Each body is followed by `callers:`/`calls:` POINTERS (file + line range) so the next hop is one more `gs --symbol` call, not a windowed Read. Use this the moment a file’s symbol list shows the method you need — it replaces the read-at-offset hunt on god-files. If the name is NOT a declared symbol (a runtime/template-injected value, a string key, a config token), it falls back to an in-tool GREP: returns the body lines where the token appears, with context — so you never shell out to grep. Overrides `view`/`match`. | |
| file_path | Yes | Relative path to the file (e.g. "src/auth/service.ts"). Suffix matches are accepted. |