Githits Code

Use GitHits for evidence from real open-source code instead of guessing from model memory.

CLI Invocation

• Run commands as githits ....
• If githits is not found, retry the same command as npx -y githits@latest ....
• Keep default text when the model reads results or chooses follow-ups. Use --json only when code consumes the raw response or text omits a required field.
• Do not expose credentials. If auth is required interactively, run githits login; use githits login --no-browser only when the user can complete the printed URL flow. In noninteractive eval/CI, do not start OAuth; report that GITHITS_API_TOKEN or prior login is required.
• If a command returns TERMS_ACCEPTANCE_REQUIRED, run githits settings terms accept or use the returned authenticated acceptance URL, then retry once.

Decision Flow

• Need a canonical target for an OSS dependency name: use githits resolve "<name>"; skip resolution for known canonical targets. Reuse only an unambiguous EXACT/HIGH best with CLEAR or NOT_APPLICABLE malicious-content status. Other or missing statuses are non-actionable; narrow or explicitly choose an actionable candidate for MEDIUM/LOW or ambiguity. Never auto-select, and do not treat CLEAR as vulnerability-free. A selected site: is docs-only.
• Need a canonical cross-project example or pattern: githits example "<focused question>"; include source repositories/citations from GitHits' generated references/provenance section. If GitHits cannot match --lang, retry with a suggested language from the error, or omit --lang.
• Need package metadata, vulnerability/advisory status, dependency graphs, or release notes: stop and use the githits-package skill instead.
• Exploring a topic in a known dependency or public repository: use githits search scoped by --in.
• Searching an exact standalone documentation site: use githits search "<topic>" --source docs --in site:<host[/path]>. If the result reports suggested site targets, retry one explicitly; suggestions are advisory targets, not aliases.
• Need file/path enumeration: use githits list <target> [paths...]; add --recursive to traverse directories. Do not probe directories with githits read.
• Need exact source changes between versions or refs: use githits code diff <unversioned-target> <from>..<to>. This is repository-wide even for package targets; use a repository-relative glob after -- to narrow known paths.
• Know the pattern: githits grep <pattern> <targets...> uses RE2 regex, case-sensitive matching, and zero context. Use -F for literal text and -i to ignore case. Lookaround and backreferences are unsupported; multi-file regex needs a literal anchor.
• Need documentation pages: use githits search "<topic>" --source docs --in <target> for topic search, or githits list site:<host[/path]> to browse a hosted site. Package/repository list targets include their local documentation files. Read emitted targets and paths with githits read; githits docs list remains a legacy package-page browser.

Core Commands

githits example "how to use express middleware"
githits example "react hooks patterns" --lang typescript

githits search "router middleware" --in npm:express@5.2.1
githits search "debounce" --in npm:lodash --source symbol
githits search '"body parser" OR multer' --in npm:express --source docs
githits search "middleware" --in site:expressjs.com --source docs
githits search-status <searchRef>

githits list npm:express@5.2.1 lib/ --recursive --limit 100
githits read npm:express@5.2.1 lib/express.js --lines 1-90
githits read 'npm:express@5.2.1#Router'
githits grep -F "require('router')" npm:express@5.2.1 --path-prefix lib/ -C 3
githits grep -F "require('router')" github:expressjs/express@v5.2.1 --path-prefix lib/
githits code diff npm:express 4.18.1..4.18.2 --name-status
githits code diff --repo-url https://github.com/expressjs/express v4.18.1..v4.18.2 -- 'lib/**/*.js'

githits list site:expressjs.com --limit 20
githits read <docsReadTarget>
githits read <docsReadTarget> --selector <heading-id>

Strategy

• For behavioral claims, prefer source, symbols, tests, and call sites over docs prose.
• Package targets scope indexed source to the package subpath; omitted versions resolve to the latest release. Repository targets cover the full indexed snapshot. Pin versions/refs for source-layout questions and report the served identity.
• Source diff compares exact trees without requiring indexed navigation. Its package target resolves versions but does not filter to a package subpath. Report resolved commits, scope, and coverage limits; capped or sibling-only results do not prove a package is unchanged, and a patch does not establish compatibility.
• For source work, locate symbols or matches first, then read a focused window with explicit --lines. Use target#symbol or --selector <name> when the exact indexed symbol is known; add an exact path to narrow ambiguous symbols. The backend decides whether a repository fragment identifies a code symbol or a documentation heading.
• For docs reads, use the search snippet when sufficient; otherwise read the page target in its header. Use search --json when an exact selector or range is required, then replay its followUp with every supplied argument unchanged. From docs list, pass docsReadTarget. Hosted/crawled HTTP(S) targets address mutable current content. A direct HTTP(S) fragment read without explicit bounds returns its heading and full subtree through the next equal-or-higher heading. Use --selector <heading-id> for a known logical heading ID without a URL fragment. Repository docs remain snapshot-addressed and keep returned ranges. When composing a direct read, add --lines only to intentionally select a current page range; either bound replaces heading selection. Historical pageId works. Use --json only for required range/source metadata or an exact search follow-up.
• For multi-step code/docs investigations, keep raw CLI output out of the final answer unless it is the evidence the user needs.
• Reuse returned targets, paths, locators, references, and ranges; never invent them. Cite the served target and report stale/provisional evidence, truncation, and coverage limits.
• For a site inventory, pass the emitted site: target and target-relative page path separately to githits read; preserve emitted read/browse action values exactly and do not repeat the target's scope in the path. Ordinary PAGE paths are reusable with their supplied target; explicit actions remain authoritative for exceptional URL/query/encoding identities. For list pagination, use --json to obtain nextCursor, then replay the same target and filters with --after <nextCursor>; do not edit the cursor. list --wait uses milliseconds.
• Partial and capped documentation coverage are usable published evidence. Report the disclosed limit, but infer neither indexing progress nor retryability from coverage; follow only searchRef and the evidence notice.
• Follow rendered continuation/recovery actions. Use search-status <searchRef> only when search explicitly supplies that follow-up; never repeat search to poll or poll a stopped reference. See references/code-and-docs.md for status/wait details.
• If discovery search returns no useful hits, do not repeat it unchanged. Follow the rendered pivots; when the query is now an exact identifier or string, switch to githits grep and read the focused match because symbol discovery may not include re-exports or generated aliases.
• If grep returns no matches, do not repeat it unchanged. Follow the returned guidance by changing the pattern, broadening the file scope, or switching to githits search for conceptual discovery.
• Grep package targets include selected hosted docs independently of --corpus and path filters. File/page headers are read locators: copy the target and optional file path, then select the matching --lines range if more context is needed. Counts cover this page; use the emitted --cursor only when needed, with identical ordered targets and matching controls.
• For indexing/freshness, use the displayed estimate to choose a longer --wait, or select a listed queryable version/ref; suggested refs may still need indexing. Site suggestions are advisory, not aliases: retry one explicitly and report omitted candidates.