Githits

Use when the user needs a canonical open-source example, usage pattern, or API snippet that is not tied to one already-known dependency/repository. Best for "how do I use X", cross-project patterns, up-to-date examples, or when package-scoped search was not enough. For inspecting a specific known package or repository, use `search`, `code_*`, or `docs_*` instead. Default output is markdown, with source repository provenance when available and a trailing `solution_id: ...` line when available. When presenting an example to a user, report the source repositories/citations from GitHits' generated references/provenance section whenever present; they are core evidence, not optional metadata. Pass `format: "json"` for `{result, solution_id?}`. Pass `solution_id` to `feedback` after using or rejecting the example. For searching indexed dependency and repository code/docs, use the unified `search` tool instead.

Use before `get_example` only when you need to force a language and are unsure of GitHits' exact language name. Finds supported language names and aliases; returns up to 5 matches. Default output is one language per line; pass `format: "json"` for the structured array.

Use after a GitHits result was helpful, unhelpful, wrong, incomplete, slow, or confusing. Submit feedback on a tool result or the GitHits experience. Two modes: 1. **Solution-tied** — pass the `solution_id` from a prior `get_example` response to rate that specific result. 2. **Generic** — omit `solution_id` to send session feedback about any tool (`search`, `code_grep`, `code_read`, `code_files`, `docs_*`, `pkg_*`) or the overall experience. `accepted` is always required (true = positive, false = negative). Add `feedback_text` for context — strongly recommended in generic mode. Pass `tool_name` when rating a specific tool result. Feeds ranking and product quality.

Use when investigating a known package, repository, or exact documentation site and you need to discover relevant docs, source files, examples, tests, or APIs before reading exact files. Search indexed dependency and repository code, docs, explicit symbols, or standalone docs with `site:<host[/path]>`. If the response includes advisory `sourceStatus[].suggestedSiteTargets`, retry one explicitly; do not treat suggestions as aliases or retry automatically. Required: `query` plus either `target` or `targets`; pass `target` or `targets`, not both. Omit `source` to let GitHits select the best sources; set it only to restrict results to docs, code, or symbols. Structured parameters combine with the `query` using AND semantics. For `source:"docs"`, code/symbol-only filters (`category`, `kind`, `file_intent`, `public_only`) are ignored because docs search does not support them. Complete by default — if required indexing or refresh outlasts the wait window, the response carries a `searchRef`; do not repeat `search`, pass that reference to `search_status`. Stale-but-serveable evidence can accompany the reference while refresh continues. A missing or ambiguous site can instead return terminal recovery guidance without a `searchRef`; follow any `suggestedSiteTargets` explicitly rather than calling `search_status`. Set `allow_partial_results: true` to permit a serveable subset of target/source pairs while others remain unavailable. Each hit's `type` tells you the follow-up tool: `documentation_page` and `repository_doc` → `docs_read` with `locator.pageId`; `repository_code` and `repository_symbol` → `code_read` with `locator.filePath` (and `locator.startLine`/`endLine` when present).

Use only after `search` returns a `searchRef`. Check progress, fetch interim hits when every runnable target/source pair is serveable, fetch partial hits from a serveable subset when the original request used `allow_partial_results: true`, or fetch final results. Pass the `searchRef` from that response as `search_ref` here (response field is camelCase; this parameter is snake_case); while it is active, continue with `search_status` instead of repeating `search`. The tool waits up to 20 seconds by default; set `wait_timeout_ms` from 0 to 60000 to change that bounded wait.

List files in an indexed dependency. First choice for file/path enumeration tasks such as files under a directory; use `path_prefix` for directory prefixes (e.g. `lib/`) and optional `extensions` for language filtering. Use this to discover paths before `code_read` (when you don't yet know the path, or it returns `FILE_NOT_FOUND`, `FILE_PATH_EXCLUDED`, or `SOURCE_FILE_INVENTORY_UNKNOWN`) and to scope `code_grep`. Address via `target.registry` + `target.package_name` (package scope) or `target.repo_url` + optional `target.git_ref` (repo scope), mutually exclusive. Narrow with `path`, `path_prefix`, `globs`, `extensions`, `file_types`, `languages`, or file-intent filters. JSON envelope shape: `{total, hasMore, files: [{path, name, language, fileType, byteSize}], resolution, indexedVersion}`. When fresh data is not ready within the wait window, responses may include `targetResolution` provenance, `indexingEstimate`, and immediately-queryable alternatives. `availableVersions` and `availableRefs` are already indexed/queryable; `suggestedRefs` are fuzzy ref hints and may need indexing first. On an `INDEXING` error envelope, retry with a longer `wait_timeout_ms` or use a version/ref from `details.availableVersions` / `details.availableRefs`.

Read one exact file from an indexed dependency; it does not list directories. Use `code_files` with `path_prefix` for file/path enumeration. **MCP cap: 150 lines per call** — broader requests (or no range) silently truncate to the first 150 lines from your start, with a `hint` describing what was returned vs. requested. Pick a focused window from a `search` / `code_grep` match. Response: `{path, language, totalLines, startLine, endLine, content, isBinary, hint?}`. Binary files set `isBinary: true` and omit `content`. Pass the same `path` emitted by `code_files`. Address via `target.registry` + `target.package_name` (package scope) or `target.repo_url` + optional `target.git_ref` (repo scope), mutually exclusive. When fresh data is not ready within the wait window, responses may include `targetResolution` provenance, `indexingEstimate`, and immediately-queryable alternatives. `availableVersions` and `availableRefs` are already indexed/queryable; `suggestedRefs` are fuzzy ref hints and may need indexing first. On `INDEXING` retry with a longer `wait_timeout_ms` or use a version/ref from error details. On `FILE_NOT_FOUND`, `FILE_PATH_EXCLUDED`, `SOURCE_FILE_INVENTORY_UNKNOWN`, or a legacy `NOT_FOUND` that specifically describes a missing file path, follow `details.action` to inspect paths available through `code_files`.

Deterministic text or regex grep over indexed dependency and repository source files. Use this when you know the pattern (literal by default; pass `pattern_type: "regex"` for RE2). Use `search` for discovery instead. Whole-target grep is the default — narrow with `path`, `path_prefix`, `globs`, or `extensions` to keep responses small. Each match's `filePath` (or text file heading) chains into `code_read.path`; pick a window around `match.line` for `code_read.start_line` / `end_line`. When an exact path returns `FILE_NOT_FOUND`, `FILE_PATH_EXCLUDED`, or `SOURCE_FILE_INVENTORY_UNKNOWN`, follow `details.action` to inspect paths available through `code_files`. When fresh data is not ready within the wait window, responses may include `targetResolution` provenance, `indexingEstimate`, and immediately-queryable alternatives in error details. `availableVersions` and `availableRefs` are already indexed/queryable; `suggestedRefs` are fuzzy ref hints and may need indexing first.

List mixed package documentation pages from hosted docs and repository-backed docs. This browses available pages; for topic search, use `search` with `source: "docs"` and pass the returned `pageId` to `docs_read`. Every entry includes a stable `pageId`, `sourceKind` (`crawled` or `repo`), and source URL; repo-backed entries also expose `repoUrl` / `gitRef` / `filePath` for exact file reads. Pass a returned `pageId` to `docs_read`. Use this to browse before reading a full page.

Read a documentation page by page ID. Works for both hosted/crawled docs and repository-backed docs. Pass `start_line` / `end_line` to fetch a slice when a page is too long. Text output is capped at 150 lines per call, including explicit larger ranges; the response carries the returned range and `totalLines` so you can target the next slice. Repo-backed results additionally include exact file follow-up metadata for `code_read`.

Use for a quick latest-version package adoption or health check: license, description, repository health, downloads, publish age, and latest vulnerability status. Latest-version package overview for dependency triage. Provide `registry` and `package_name` (for example `npm` + `express`). Default text returns license, description, repository popularity (stars/forks/issues and [ARCHIVED] when applicable), downloads, publish age, and vulnerability status. Set `verbose: true` for GitHub language/topics/last-pushed, recent advisories, and recent changes. Pass `format: "json"` for structured fields. Use `pkg_vulns` for version-specific vulnerability details.

Use when the user asks whether a package or pinned version has known vulnerabilities, advisories, CVEs, malware, affected ranges, or fix versions. Check known vulnerabilities for a package on npm, PyPI, Hex, Crates, NuGet, Maven, Packagist, RubyGems, Go, or Swift (vcpkg and Zig are not supported for vulnerability data). Returns a count summary, each advisory with OSV ID, severity, affected ranges, and fix versions. Malicious-package advisories surface in a separate bucket. Example: `{"registry":"npm","package_name":"lodash","version":"4.17.20","min_severity":"high"}`. Pass `version` to inspect a pinned release; omit it for latest. Default text is capped for readability; use `verbose:true` for all selected advisory rows or `format:"json"` for the complete envelope. Use `min_severity` to filter to a threshold (`low`, `medium`, `high`, `critical`) and `include_withdrawn` to also see retracted advisories. Use `advisory_scope:"non_affecting"` to list historical advisories that do not affect the inspected version, or `advisory_scope:"all"` to list affected and historical advisories together.

Use when the user asks what a package depends on, wants dependency groups, or needs a bounded transitive dependency footprint. Analyze a package's dependency graph. Lists direct runtime dependencies with resolved versions; non-runtime groups are omitted by default. Use `lifecycle` with a concrete value for matching dependency groups, or `all` for every available group. Runtime group rows include resolved versions when available. Pass `max_depth` to add a `transitive` block with the capped install footprint, conflict detection, and circular-dependency flags; layer `include_importers: true` on top when you also need per-package provenance. Supports npm, PyPI, Hex, Crates, Zig, vcpkg, RubyGems, Go, and Swift.

Use when the user asks what changed in a package, wants release notes, or needs changelog evidence for a manual upgrade review. Release notes for a package or GitHub repo, newest-first. Default latest mode returns the ten most recent entries (`limit` 1–50). With `from_version`, returns every entry in the `[from_version, to_version]` range (range mode, no count cap). Address via `registry` + `package_name` or `repo_url` (mutually exclusive). Response includes optional `source` (`"releases"` / `"changelog_file"` / `"hexdocs"`) when a concrete changelog source exists, `mode` (`"latest"` or `"range"`), and entries with markdown body previews. Example: `{"registry":"npm","package_name":"express","limit":2}`. Text output previews 10 body lines by default; use `body_lines` to tune the preview or `verbose:true` for full text bodies. Set `omit_bodies: true` for a version / date / URL timeline only; pass `format: "json"` for the complete structured envelope. Package-version entries without changelog text succeed with `source` omitted; no-source plus no entries returns `NOT_FOUND`. Supports npm, PyPI, Hex, Crates, NuGet, Maven, Zig, vcpkg, Packagist, RubyGems, Go, and Swift.

Use when the user asks whether to accept, assess, review, or investigate a dependency update from one version to another. Report package-upgrade evidence by comparing current and target versions with direct vulnerability checks, changelog range evidence, target deprecation metadata, peer dependency changes, and optional transitive evidence diffs. The tool reports facts only and does not assign risk or decide whether to accept an upgrade. Use this instead of inferring acceptability from semver, including patch bumps. Accepts either one package via registry/package_name/current_version/target_version or batch `packages[]`. Batch execution is capped internally to avoid flooding the package-intelligence backend.