natsukium/ghq

ghq - Local Repository Management

ghq clones remote repositories into a predictable, deduplicated directory tree under ghq root (here: ~/src/private, layout <host>/<owner>/<repo>). Once a repo is there, reading it is a local filesystem operation — no API calls, no rate limits, no re-download next time.

Why this skill exists

When inspecting source code, the wasteful patterns are:

• gh api repos/.../contents/<file> per file — burns a request and base64 round-trip per read, can't grep across the tree, can't follow imports.
• git clone into /tmp (or mktemp -d) — re-downloads on every session, leaves the repo unfindable later, wastes bandwidth and disk.
• WebFetch of raw.githubusercontent.com URLs — same problem as gh api, plus no recursion.

ghq get solves all three: it's idempotent (no-op if the repo is already cloned), it puts the repo in a path you can find again with ghq list, and once local you can use Read, Grep, Glob, and ast-grep freely.

The workflow

1. Check first — ghq list <repo> (or ghq list -e <owner>/<repo> for exact match). If it prints a path, the repo is already there; skip the clone.
2. Clone if missing — ghq get <owner>/<repo>. Add --shallow for one-off inspection of a specific commit's tree, or --partial blobless if the repo is huge (e.g., nixpkgs, linux, chromium) and you only need to navigate before reading a few files.
3. Resolve the path — ghq list -p -e <owner>/<repo> returns the absolute path. Use this with Read/Grep/Glob, not cd.
4. Update only when needed — ghq get -u <owner>/<repo> to pull latest. Don't update reflexively; a stale clone is usually fine for "how does X work" questions.

Anti-patterns

<examples> <example type="bad"> <description>Fetching files individually via the GitHub API</description> <bad>gh api repos/NixOS/nixpkgs/contents/pkgs/development/interpreters/python/default.nix</bad> <good>ghq get NixOS/nixpkgs && Read $(ghq list -p -e NixOS/nixpkgs)/pkgs/development/interpreters/python/default.nix</good> </example> <example type="bad"> <description>Cloning into /tmp for "just this session"</description> <bad>git clone --depth 1 https://github.com/facebook/react /tmp/react</bad> <good>ghq get --shallow facebook/react # ends up at ~/src/private/github.com/facebook/react, reusable</good> </example> <example type="bad"> <description>Using WebFetch on raw.githubusercontent.com to read source</description> <bad>WebFetch https://raw.githubusercontent.com/owner/repo/main/src/foo.ts</bad> <good>ghq get owner/repo && Read $(ghq list -p -e owner/repo)/src/foo.ts</good> </example> </examples>

Good examples

<examples> <example> <user>Check how nixpkgs handles uv2nix</user> <agent>I'll make sure nixpkgs is cloned, then grep it locally. `ghq get NixOS/nixpkgs` (no-op if present) `rg -l uv2nix $(ghq list -p -e NixOS/nixpkgs)/pkgs`</agent> </example> <example> <user>Look at how React implements useEffect</user> <agent>I'll fetch React once and search the source tree. `ghq get facebook/react` Then `Grep` for `function useEffect` inside `$(ghq list -p -e facebook/react)`.</agent> </example> <example> <user>I want to see the changes in https://github.com/owner/repo/pull/42</user> <agent>That's a PR review, not source-code reading — using `gh` instead: `gh pr diff 42 --repo owner/repo`. (If I then need to explore the surrounding code, I'll `ghq get owner/repo`.)</agent> </example> <example> <user>The linux kernel has a function called vmalloc, can you find where it's defined?</user> <agent>Huge repo — partial clone keeps it tractable. `ghq get --partial blobless torvalds/linux` `rg -n 'void \*vmalloc\(' $(ghq list -p -e torvalds/linux)`</agent> </example> </examples>

When NOT to use ghq

• PR/issue/workflow operations — use gh (gh pr view, gh issue view, gh run view). Those aren't source code.
• A single, never-revisited file from a documentation URL — WebFetch is fine; cloning a repo for one README is overkill.
• Inside this dotfiles repo itself — already on disk; just Read/Grep directly.