gh-search

gh-search

Search GitHub for concrete code before guessing. Search for exact API names, method names, and small string snippets that must appear in a working example.

Workflow

1. Search code for the exact method or pattern.
2. Collect repo names from promising hits.
3. Rank repos by stars and credibility.
4. Read the best few examples in full, not just the first random hit.
5. Report repo URLs and file paths of the best examples so they are easy to inspect later.

1. Search code

Search for one unique term, not a description. GitHub code search matches literal tokens in files. Natural-language phrases ("iOS HID wheel scroll bluetooth mouse") return nothing, because no file contains those words together. The best queries use one term that only appears in code doing what you want:

• a specific function or class name from the API you use: IOHIDScrollAccelerator, registerForL2CAPChannelOpenNotifications, IOHIDEventGetTimeStamp
• a magic number or constant: SCROLL_CLEAR_THRESHOLD_MS, "0x09, 0x38", kHIDUsage_GD_Wheel
• an exact string in quotes that the code must contain: '"setClassOfDevice(0x002540"'

# one unique API name found the iOS scroll accelerator source and a decompiled iOS 18 build
gh search code 'IOHIDScrollAccelerator' --limit 30
# then add ONE more token to narrow, not a sentence
gh search code 'IOHIDScrollAccelerator SCROLL_CLEAR_THRESHOLD_MS'

If a query returns nothing, remove terms; do not add more. Start from names you already know (functions, constants, report IDs you use in your own code), then read the hits to learn new unique names and search those.

Combine several clues from the pattern only when each clue is a real code token.

# one concrete API
gh search code 'std.process.Child.init "stdout_behavior = .Pipe" language:Zig' --limit 30

# bigger pattern with multiple clues
gh search code 'std.process.Child.init "stdout_behavior = .Pipe" "stderr_behavior = .Pipe" "std.Thread.spawn" language:Zig' --limit 30

# restrict by filename, extension, owner, or repo
gh search code 'minimumReleaseAge' --filename pnpm-workspace.yaml
gh search code 'createTaggedError' --extension ts --owner remorses
gh search code 'ThreadsafeFunction' --repo napi-rs/napi-rs

Qualifiers work inline too: language:go, path:src, filename:package.json. Quote exact strings with double quotes inside the single-quoted query.

gh search code uses GitHub's legacy code search API. No regex. Results can differ from github.com. If nothing matches, drop a clue and retry.

gh search issues and gh search repos wrap one quoted argument as a phrase (q=( "ios scroll wheel" )), which almost never matches. Pass words as separate arguments: gh search issues iPhone scroll --repo owner/repo.

HTTP 502/503/504 from search is transient. Wait a few seconds and retry once; do not drop the query.

2. Collect repos from hits

gh search code 'napi::bindgen_prelude "ThreadsafeFunction" language:Rust' --limit 50 \
  --json repository,path,url \
  --jq '.[] | "\(.repository.nameWithOwner)\t\(.path)"' | sort -u

3. Rank by stars

Code search JSON has no star count. Look it up per repo:

for r in owner1/repo1 owner2/repo2; do
  gh repo view "$r" --json nameWithOwner,stargazerCount --jq '"\(.stargazerCount)\t\(.nameWithOwner)"'
done | sort -rn

Or search repos by topic directly, sorted by stars:

gh search repos 'command runner stdout stderr streaming zig' --sort stars --limit 30 \
  --json fullName,stargazersCount,description,url

4. Read the best examples

Read whole files, not only the matching line. For deep reads, fetch the repo source locally:

opensrc path owner/repo          # prints cached local path
gh api repos/owner/repo/contents/path/to/file.ts --jq .content | base64 -d

Prefer opensrc path over cloning into tmp.

5. Report

Always include clickable URLs, for example:

• https://github.com/owner/repo/blob/main/src/file.ts (1.2k stars): uses X with Y option