> ## Documentation Index > Fetch the complete documentation index at: https://docs.githits.com/llms.txt > Use this file to discover all available pages before exploring further. # Code: search, grep, files, and source > Search indexed code, grep matches, list files, and read exact source lines. The deterministic Code tools let your agent search indexed packages and repositories, grep source, list files, and read exact lines at a package version or repository ref. For generated implementation examples, use [Example](/tools/code-examples). GitHits indexes public repositories on demand. When a search needs indexing, follow the response's progress or retry guidance. If it includes a `searchRef` and an active status (`PENDING`, `INDEXING`, or `SEARCHING`), use `search_status` to follow that search. Some responses also include provisional hits you can use while indexing continues. **Supported languages for code indexing:** Bash, C#, C++, CSS, Dart, Elixir, Erlang, Go, Java, JavaScript, Kotlin, Lua, Markdown, PHP, Proto, Python, R, Ruby, Rust, Scala, SCSS, Swift, TypeScript, Zig, and more. `search` is the primary discovery tool. It searches across code, documentation, and explicit symbols in any indexed package or GitHub repository. Use it when you need to find where something is defined, which files handle a specific concern, or which docs page explains a behavior. Query syntax supports implicit AND, uppercase OR, grouping with parentheses, negation with `-`, quoted phrases, and semantic qualifiers: | Qualifier | Description | Example | | - | - | - | | `kind:` | Symbol kind | `kind:function` | | `category:` | Symbol category | `category:callable` | | `path:` | File path component | `path:src/auth` | | `lang:` | Language | `lang:typescript` | | `name:` | Symbol name | `name:createServer` | | `intent:` | File intent | `intent:test` | Scope targets with the registry prefix format (`npm:react`, `pypi:requests`) or a full GitHub URL (`https://github.com/expressjs/express`). In the CLI, pass targets with repeatable `--in` flags. In MCP, pass `target` for one target or `targets` for multiple targets. **CLI usage** ```bash theme={null} npx githits@latest search "createServer" --in npm:express npx githits@latest search "middleware error handling" --in npm:express@4.18.0 npx githits@latest search "kind:function authentication" --in https://github.com/supabase/supabase npx githits@latest search "pub sub Redis" --in pypi:python-socketio ``` **Key parameters** Discovery query string. Supports AND (implicit), OR (uppercase), parentheses, `-` negation, quoted phrases, and semantic qualifiers (`kind:`, `category:`, `path:`, `lang:`, `name:`, `intent:`). Single search target. Package format: `npm:react@18.2.0` or `npm:react` for latest. Repository format: `https://github.com/facebook/react`. Multiple search targets. Use either `target` or `targets`, not both. Restrict results to `code`, `symbol`, or `docs`. Omit to let GitHits choose the best indexed sources. See [Documentation](/tools/documentation-access) for docs-focused search, listing, and reading workflows. Returns available hits while other targets or sources prepare, plus a `searchRef` for continuation. From 0.27.0, defaults to `true`. Set `false` to wait for all runnable targets and sources before returning hits; a complete interim result may still be returned during a refresh. Maximum results to return (default 10, max 100). **Provisional results** While a target is still indexing, `search` can return provisional repository-code results. Provisional hits come from an exact-commit snapshot and are immediately usable, but the session is not finished. The response marks the results as still indexing, reports the exact served identity and `PROVISIONAL` freshness instead of the ref you requested, and keeps the active `searchRef` so you can continue with `search_status`. **Semantic matches** Repository code and repository docs hits show the matched source: the enclosing declaration scopes around the match, followed by the exact matched source with its original line numbers: ```text theme={null} [1] npm:pkg@1.2.3 src/client.ts:142-145 [repo code] - class Client | lines 20-620 - method Client.send | lines 120-165 142 | const response = await transport(request); > 143 | return response; ``` * The header carries the read target, path, and matched line range. Package hits pair the registry, package, and version with the package-relative path. Repository hits pair the repository with its exact served commit and the repository-root path. * Scope rows list the enclosing declarations outer-to-inner, each with its kind, qualified name, and inclusive declaration line range. Pick your follow-up `read` range directly from these rows: the header range for the local match context, or an enclosing declaration range for the full definition. No separate per-hit read command is printed. * Source lines keep their original numbering, indentation, and boundaries. A `>` gutter marks lines that contain matches and stays visible without color. Omitted lines, cropped long lines, truncated scope chains, and incompletely highlighted matches carry explicit ASCII notices. Search text only shows source the backend proved matched: * A repository hit without proven matched source renders as a single `candidate` header line. No source lines, scope rows, or summary appear under it: ```text theme={null} [2] npm:pkg@1.2.3 examples/auth/index.js:75-82 [repo code, candidate; visible terms: login, auth, session] ``` * The line range is the backend's bounded read window. Use it as a place to inspect with `read`. It does not prove the match location. * For a bare identifier query, `visible terms:` lists the query fragments (split on camel case and underscores) visible in the title or displayed path when those indexed fields contributed to the hit. If no fragment is visible, the header names the contributing indexed fields instead, for example `indexed: path/identifiers`. If field provenance is unknown, the header shows only `candidate`. * When a known declaration in the same file contains the window, the header ends with its kind and qualified name, for example `- interface AuthSessionStore`. * `visible terms` are substrings observed in the returned text. They do not prove a match and do not explain the ranking. * Older results without matched source still show `Snippet unavailable` and keep their locators. * Crawled documentation pages use a structural preview of the page with match highlighting instead of source lines. * Explicit symbol hits show qualified identity with signature detail, kind, and any differing definition range, without a summary body. In JSON output, each repository hit's `locator` keeps the legacy `filePath`, `startLine`, and `endLine` and adds: * `commitSha` — the exact served revision * `repositoryFilePath` — the repository-root path (as opposed to the target-relative `filePath`) * `evidenceRange` — the focused match range * `indexedRange` — the originally indexed range * `symbolContext` — the enclosing symbol's `name`, optional `qualifiedPath` and `kind`, and a normalized lowercase `relation`: `encloses_match` (a proven enclosing definition, always with a complete `definitionRange`) or `associated_with_indexed_chunk` (associated context, `definitionRange` optional) JSON hits additionally carry the structured results behind the text rendering: * `repositoryEvidence.semanticContext` — the enclosing declaration `scopes` (outer-to-inner, with kind, qualified path, inclusive declaration ranges, parameter names, and return type) and a `preferredRead` locator with exact attributed read coordinates * `repositoryEvidence.matchedSource` — the proven numbered source: inclusive line bounds, match anchor, range kind, per-line text with grapheme-offset highlights, and crop/omission flags * `repositoryEvidence.bm25MatchFields` — the indexed fields that contributed matches (`SYMBOL_NAME`, `FILE_PATH`, `DOCUMENTATION`, `SOURCE_IDENTIFIER`). A known list is complete and ordered; `null` means the breakdown is unknown, not that nothing matched. * `documentationPreview` — the structural preview text and highlight ranges for crawled documentation hits Since 0.23.0, `search` and `search_status` no longer emit `summary`, `highlights.summary`, hit `contentSafety`, or `repositoryEvidence.focusedSource`. JSON consumers must use `matchedSource`, indexed-field provenance, semantic context, and `documentationPreview` as appropriate. A candidate header is a navigation aid; inspect its bounded window before treating it as a source match. Repository hits also provide a `followUp` `read` command. Prefer this emitted action so the target, path, and bounds stay consistent. Package-attributed repository code and docs use the served package target and target-relative path; repository targets retain the served revision and repository-root path. JSON keeps snapshot provenance. When a preferred range exceeds the 300-line MCP `read` cap, the generated command requests a bounded window while the structured ranges remain unchanged. Search text does not print a read command under each hit. Use the target and location from the header for direct reads. For the exact backend-selected section, request JSON and replay the complete `followUp`, including its target, path, selector, and bounds. **Follow-up tools** Each hit's `type` field tells you which follow-up tool to use: * `repository_code` or `repository_symbol` → `read` with the compact `target` and exact `path`. In text output, build the call from the hit header and scope rows. In JSON, prefer the hit's `followUp` command, which reads the preferred range at the exact served revision. * Repository documentation hits → use the emitted `followUp`, or the target, path, and range in the text header. These reads return indexed file content. * Hosted documentation hits → `read` with the result's `docsReadTarget` as `target` (and no `path`), or its `pageId` when no target is emitted. `search_status` lets you follow up on a `search` response that returned a `searchRef` instead of hits. This happens when indexing is still running. Pass the `searchRef` from the prior search response to check progress, fetch partial hits, or retrieve final results. **Session states** Every `search` and `search_status` response reports a session status. The status set is open: the backend can introduce new values, and clients preserve them instead of rejecting the response. | State | Statuses | What to do | | - | - | - | | Active | `PENDING`, `INDEXING`, `SEARCHING` | Poll `search_status` with the same `searchRef`. | | Provisional results | Active status with `PROVISIONAL` freshness | Use the returned hits now. They come from an exact-commit snapshot served while indexing continues. The `searchRef` stays active for continuation. | | Terminal | `DEFERRED`, `TIMEOUT`, `FAILED` | Stop polling. Use any results the response returned, then run a new `search` later for a fresher snapshot. | | Unrecognized | Any other value | The status is preserved verbatim with any returned results. Do not poll the same `searchRef`, and do not treat it as "no hits" or as completion. Run a new `search` later. | `DEFERRED` is terminal on both the initial `search` response and `search_status` progress. It means background lifecycle work continues outside the session, so the `searchRef` no longer advances. Any hits already disclosed remain usable. **CLI usage** ```bash theme={null} npx githits@latest search-status ``` **Parameters** The `searchRef` value from a prior `search` response. Pass it through unchanged (the response field uses camelCase; this parameter uses snake\_case). Maximum time to wait for progress, 0–120,000 milliseconds (default 30,000). The 120-second ceiling matches the upstream HTTP deadline; GitHits picks a longer wait automatically when the response carries indexing-time estimates. `text` (default) for compact output, or `json` for the structured result. The former `text-v1` value is no longer accepted; omit the parameter or pass `text` instead. With the default `allow_partial_results: true`, the `search_status` response may include hits from sources that have finished so far, with pagination support via `nextOffset`. `grep` searches ordered package, repository, and hosted documentation targets for a known pattern. Use `search` for topics, `list` to find paths, and `read` for more context. Since `@githits/mcp` 0.25.0, `grep` replaces `code_grep`. Refresh local MCP tool discovery and migrate the arguments; this is not just a rename. Hosted availability depends on the deployed server version. CLI `githits grep` was added in 0.24.0; legacy `githits code grep` remains available with its older flags and defaults. The defaults are RE2 regex, case-sensitive matching, zero context lines, and all indexed repository files. To preserve the old literal, case-insensitive behavior, set `pattern_type: "literal"` and `ignore_case: true` explicitly. **MCP example** ```json theme={null} { "targets": [ {"target": "npm:express@5.2.1", "path_selectors": [{"kind": "prefix", "value": "lib/"}]}, {"target": "site:expressjs.com/en/5x"} ], "pattern": "router", "pattern_type": "literal", "ignore_case": true, "context_lines_after": 2 } ``` Package targets also include their selected hosted documentation. `corpus` and `path_selectors` filter repository files only; they do not exclude a package's hosted docs. Site entries accept only `target`. **CLI usage** ```bash theme={null} npx githits@latest grep -Fi 'router' npm:express site:expressjs.com/en/5x npx githits@latest grep -C 2 'app\.use\(' github:expressjs/express --path-prefix lib/ ``` See the [`grep` CLI reference](/cli/commands#npx-githits-latest-grep) for all flags. **Parameters** One to 20 ordered objects. Each contains `target`, plus optional `corpus` (`source`, `documentation`, or `all`) and `path_selectors` for package or repository targets. Each path selector has `kind` (`exact`, `prefix`, or `glob`) and `value`; selectors form a union relative to that target's root. Omit both controls for `site:` targets. Pattern of 1–200 UTF-8 bytes. RE2 regex does not support lookaround or backreferences; multi-file regex requires a literal anchor. Unsupported patterns fail explicitly. `regex` or `literal` substring matching. Set to `true` for case-insensitive matching with Unicode folding. Lines before each match, 0–10. Lines after each match, 0–10. Maximum occurrences across all scopes on this page, 1–1000. This is a global cap, not a per-file limit. Opaque continuation cursor. Reuse the same ordered targets, pattern, and matching controls. Empty starts the first page. Restart without a cursor if it expires. First-page preparation wait in milliseconds, 0–300,000. Continuation never waits. `text` for grouped matches, read locators, coverage, and continuation guidance. Use `json` for detailed hit and scope fields, read actions, and byte coordinates. Text groups matches under numbered file or page headers. Use the emitted read locator and line numbers for more context. Match rows use `:` after the line number; context rows use `-`. Coverage and counts describe this page only. A small match cap can leave scopes unvisited; follow the returned cursor to continue. Hosted pages may change between `grep` and `read`. `list` lists the files and documentation paths in one known package, repository, or hosted documentation site. Use it to discover paths before calling `read`, to scope a `grep`, or to explore the structure of an unfamiliar package. Use `search` instead when your agent knows the topic. Since `@githits/mcp` 0.24.0, `list` replaces the retired `code_files` and `docs_list` MCP tools. If you upgrade an existing MCP client, refresh its tool catalog so it discovers `list`. The hosted MCP server exposes `list` once GitHits deploys `@githits/mcp` 0.24.0 to it. A package target covers that package's own source tree. A repository target covers the whole snapshot. Both include source and documentation files. Hosted documentation is a separate inventory that requires an explicit `site:` target. See [Documentation](/tools/documentation-access#list) for site inventories. Select entries with `paths`. Each entry is a target-relative literal path or glob, and multiple entries form a union. Selected directories show their immediate children unless `recursive` is `true`. Glob depth is independent of recursion. Text output starts with a `# source ` header and a `read $path` follow-up hint, followed by one path per line. Directory entries end in `/`. When more entries exist, the output ends with the `after` cursor to pass on the next call. Reuse the same target, paths, and options with that cursor, and treat it as opaque. ```text theme={null} # source npm:express@5.2.1 | follow up with "read npm:express@5.2.1 $path" | more results available History.md LICENSE lib/ More results: reuse the same target, paths, and options with: after="" ``` **CLI usage** ```bash theme={null} npx githits@latest list npm:express@5.2.1 npx githits@latest list npm:express@5.2.1 lib/ --recursive --limit 100 npx githits@latest list github:expressjs/express 'lib/**/*.js' npx githits@latest list github:expressjs/express --intent test --recursive -s ``` `npx githits@latest code files` is deprecated but keeps its existing behavior for compatibility. See the [`list` command](/cli/commands#npx-githits-latest-list) for all CLI flags. **Parameters** Package such as `npm:express@5.2.1`, repository such as `github:expressjs/express`, or hosted docs site such as `site:expressjs.com`. Target-relative literal paths or globs, such as `["lib/", "lib/**/*.js"]`. Entries form a union. Omit or pass `[]` to browse the root. Expand selected directories to all descendant files. Without it, selected directories show immediate children. Source inventories only. Case-insensitive classifications such as `source` or `doc`. Use `paths` globs for extensions. Source inventories only. Case-insensitive language names such as `javascript` or `typescript`. Source inventories only. File intents: `PRODUCTION`, `TEST`, `BENCHMARK`, `EXAMPLE`, `GENERATED`, `FIXTURE`, `BUILD`, or `VENDOR`. Maximum entries to return (1–500). Opaque `nextCursor` from a prior `list` response. Reuse the same target, paths, filters, recursion, and limit. Maximum wait for source indexing in milliseconds (0–300,000). `text` (default) or `json`. Use `json` for exact entry kinds (`FILE`, `PAGE`, or `DIRECTORY`), read and browse actions, lifecycle metadata, and `nextCursor`. `read` is the one advertised reader on the MCP surface. Pass a package or repository `target` and exact `path` to read a file, including repository documentation. For hosted documentation, pass a page locator alone or, since 0.23.0, an emitted `site:` target plus its target-relative page path. The resolved result determines code or documentation presentation. See [Documentation](/tools/documentation-access#read) for hosted page reads. Use the read locator from `search`, `grep`, or `list` to target a file, then set `start_line` and `end_line` to fetch only the window you need. Repository search hits supply read coordinates directly: the hit header and scope rows in text output, or the ready-made `followUp` read command in JSON, both pinned to the exact served revision. Since `githits` and `@githits/mcp` 0.22.0, you can pass `selector` to read an indexed code symbol, such as a function or class name, without knowing its line range. A symbol read returns the symbol's indexed definition range by default. Add `path` to restrict the lookup to that exact file, or omit it to search the whole code target. `path` always means an exact target-relative file. Either explicit bound overrides the definition range. The hosted MCP server exposes `selector` once GitHits deploys `@githits/mcp` 0.22.0 to it. When a symbol selection returns no source, the response carries a typed status with recovery guidance: * `AMBIGUOUS`: several indexed symbols match. The response lists up to 10 candidates. Retry with one candidate's exact `path`. * `NOT_FOUND`: no indexed symbol matches. The response lists up to 10 suggestions. Retry with a suggestion, or locate the symbol with `search`. * `SNAPSHOT_UNSUPPORTED`: the indexed snapshot does not support symbol selection. Find the definition with `search` or `grep`, then `read` the exact `path` with `start_line` and `end_line`. The MCP surface returns **150 lines by default** and allows explicit ranges up to **300 lines per call**. When you omit `end_line`, the read returns 150 lines from your start point. When you pass an explicit `start_line`/`end_line` range, the read honors it up to 300 lines. Broader ranges truncate and include a `hint` describing what was returned versus requested, with the continuation `start_line` for the next call. The CLI command `npx githits@latest read` has no line cap for piping. **CLI usage** ```bash theme={null} npx githits@latest read npm:express@5.2.1 lib/application.js npx githits@latest read npm:express@5.2.1 lib/application.js --lines 120-200 npx githits@latest read github:expressjs/express@v5.2.1 lib/express.js npx githits@latest read 'npm:express@5.2.1#createApplication' npx githits@latest read npm:express@5.2.1 --selector createApplication npx githits@latest read npm:express@5.2.1 lib/express.js --selector createApplication npx githits@latest read --repo-url https://github.com/expressjs/express --git-ref v5.2.1 --selector createApplication ``` With `--repo-url` and `--selector`, pass at most one positional path. The CLI rejects an extra path argument. CLI 0.22.1 and MCP 0.22.0 also support compact `target#symbol` reads, with an optional exact path. Do not combine a compact fragment with `selector`. The `npx githits@latest code read` and `npx githits@latest docs read` commands remain available as deprecated commands with their existing flags. Use top-level `read` for site paths, compact symbol targets, and `--selector`. **Parameters** With `path`: a compact package or repository target, or an emitted `site:` target for hosted documentation. Without `path`: a documentation locator, a compact `target#symbol`, or a code target with `selector`. Pass emitted locators through unchanged. Exact package- or repository-relative file path from discovery results, or a target-relative page path for an explicit `site:` target. Omit when passing a complete documentation locator; an empty string counts as omitted. Use `list` to discover source paths. Indexed code symbol name, or a logical documentation heading ID. With a code path, searches only that exact file; with a site path, selects a hosted heading. Without a code path, searches the whole code target. Selected code returns its definition range unless you set a bound. Do not combine with a URL fragment or compact `target#symbol`. Starting line (1-indexed). For code reads, omit to start at line 1. For documentation pages, either bound replaces a URL fragment with a page-relative range. Ending line (inclusive). Must be ≥ `start_line` when both are set. Text output returns 150 lines without an end, up to 300 with one. Code JSON is also bounded; documentation JSON preserves the backend selection. Code indexing wait, 0–60,000 ms (default 30,000). Validated for documentation reads but not forwarded, because the docs backend has no indexing wait. Read only the lines you need — a focused window around the symbol or grep match you are investigating. The 150-line default keeps reads focused; use an explicit range up to 300 lines when you know the required bounds, such as reading a modest whole file without pagination. Each retry costs additional context budget, so aim for one well-sized read per location. Response fields for code reads: `{path, language, totalLines, startLine, endLine, content, isBinary, hint?}`. Binary files set `isBinary: true` and omit `content`. Documentation reads keep their existing docs-side response shape. Available by default in CLI and MCP 0.26.0. Hosted availability depends on the deployed MCP version. `code_diff` compares repository trees resolved from two package versions or two public GitHub refs, left-to-right. Use it to inspect changes between exact versions when you want git-shaped output. For upgrade review — vulnerabilities, changelog entries, deprecation, peer/dependency changes — call `pkg_upgrade_review` instead; raw diffs do not prove API compatibility or upgrade safety. Pass an unversioned target with separate MCP `from` and `to` values. The CLI uses a required `..` range; three-dot merge-base syntax and `--git-ref` are rejected. **Scope is always repository-wide.** Package addressing resolves package, repository, version, and exact-commit identity, but every raw diff is repository-wide. `code_diff` does not discover or filter to a package directory. Sibling package paths may appear in a monorepo, and a bounded relevance-ranked result may contain no files from the addressed package. That absence does not prove the package is unchanged. MCP `path_glob` or a CLI glob after `--` narrows repository paths without changing the scope. MCP defaults to `name-status`; the CLI defaults to `--patch`. Use `stat` for change counts or a scoped `patch` for content. File bounds apply after relevance ranking; patch-byte bounds apply only to patches. MCP text previews each patch at 320 UTF-8 bytes. Use `format: "json"` for the full returned patch, still subject to byte limits and content coverage. Check truncation and content-safety warnings before using a patch; incomplete, filtered, byte-escaped, or omitted content is not safely applicable. **MCP parameters** | Parameter | Description | | - | - | | `target` | Required unversioned target, such as `npm:express` or `github:expressjs/express` | | `from`, `to` | Required exact package versions or repository refs | | `view` | `name-status` (default), `name-only`, `stat`, or `patch` | | `path_glob` | One non-empty repository-relative glob; supports literals, `*`, `?`, whole-component `**`, and backslash escapes. No braces, character classes, `!`, or Git pathspec magic | | `max_files` | Returned-file limit, 1–300 | | `max_patch_bytes` | Aggregate patch-byte limit, 1,024–2,097,152; requires `view: "patch"` | | `format` | `text` (default) or `json` | Pass `--verbose` to show exact version or ref resolution and effective repository-scope diagnostics in text output. **CLI usage** ```bash theme={null} npx githits@latest code diff npm:express 4.18.1..4.18.2 npx githits@latest code diff npm:express 4.18.1..4.18.2 --stat npx githits@latest code diff npm:express 4.18.1..4.18.2 --name-status -- 'lib/**/*.js' npx githits@latest code diff --repo-url https://github.com/expressjs/express v4.18.1..v4.18.2 --name-only ``` The selected Git-like view goes to stdout. Truncation, content-safety, and display-only path warnings go to stderr. Empty authoritative diffs exit `0`. Caller-selected `--max-files` and `--max-patch-bytes` bounds may intentionally produce partial patches and still exit `0` with warnings. Unexpectedly incomplete or non-applicable plain patches are suppressed and exit `1`; the `--stat`, `--name-only`, `--name-status`, and JSON views preserve their structured partial results. ## Output formats Every format-selectable MCP tool accepts a `format` parameter with exactly two values: `text` (the default) and `json`. Use `text` for reading and tool follow-ups; it is token-efficient, and you can pass returned paths, IDs, and line ranges directly to subsequent tools. Use `json` only to parse responses in code or to obtain fields absent from text. The former `text-v1` value is rejected as of CLI and `@githits/mcp` 0.13.0; callers that passed it explicitly should omit `format` or send `text`. Rendering and JSON payloads are unchanged. ## MCP tool reference | MCP tool | CLI command | Purpose | | - | - | - | | `search` | `npx githits@latest search` | Unified discovery across code and symbols | | `search_status` | `npx githits@latest search-status` | Poll async indexing and fetch results by `searchRef` | | `grep` | `npx githits@latest grep` | Find regex or literal matches across ordered source and documentation targets | | `list` | `npx githits@latest list` | Browse a package, repository, or explicit hosted documentation site | | `read` | `npx githits@latest read` | Read an exact file, code symbol, hosted page, or documentation heading | | `code_diff` | `npx githits@latest code diff` | Compare source across versions or refs | For target discovery, use [`resolve_target`](/tools/target-resolution). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.