Two questions arrive dressed as one: where does this happen, and why is it like this.
Answer the first from the layout and the code, the second from the commits — and never
guess at either from a file name.
get_repository_tree with recursive: truereturns the whole layout in one call. On a large repository, set path_filter to a
prefix and take the top level first; the directory names alone usually identify the
entry points, the tests and the generated code.
get_file_contents on theREADME and any contributing guide. They state intent, which no amount of code
reading recovers.
list_branches shows what exists besidethe default branch, and list_tags shows whether the project versions itself. If it
does, the newest tag is a better reading point than the default branch, because it
is a state someone chose to publish.
search_code with repo:owner/nameand a distinctive symbol goes straight there. Qualify with path: andlanguage: to cut noise; quote a phrase for an exact match. Keep the query under
256 characters, and use fields to return only path and text_matches when you
are locating rather than reading.
get_file_contents gives itthe context that decides whether it is the definition, a caller, or a test.
list_commits with path set to the filegives that file's history in change order. This is where the layout question ends
and the history question begins — references/history-investigation.md covers the
rest.
you actually read, so the next person can start where you finished.
how exploration turns into a tour of the wrong directory.
search_code spans all of GitHub unlessrepo: or org: narrows it. An unscoped query returns other people's code, which
looks plausible and answers nothing.
file. Pulling whole directories of contents to find one symbol is slow and buries the
answer.
will match a search and tell you nothing about intent. Exclude them by path: once
you have seen them appear.
default branch, the two describe different software; say which one you read.
recursive and path_filter — the difference between one call and a hundred, andbetween a readable tree and an unreadable one.
ref versus sha on get_file_contents — ref reads a branch or tag as it is now,sha reads one exact commit. Only the second is stable while you work.
query qualifiers on search_code — repo:, org:, path:, filename:,extension:, language:, and NOT for exclusions. Ordering belongs in sort andorder, never inside the query text.
path on list_commits — restricts history to one file, which is the single mostuseful narrowing available.
detail on get_commit — stats names the changed files, full_patch includes thediff and can be enormous. Ask for none when you only want the message and author.
fields — on both the tree read and the searches, returning fewer fields is whatkeeps a wide exploration affordable.
Everything here is read-only, so the risk is not damage but scope: an exploration that
quietly becomes an audit, or that reads far more than was asked for.
organisation is a different task from reading one repository, and costs
correspondingly more. Ask before widening.
of files or a very large diff, say what it would take and get agreement rather than
starting.
"so fix it". Nothing here writes; stop at the finding and confirm the next step
separately.
Narrow with path_filter rather than treating the partial tree as complete, and say
it was partial.
literally, spelled differently, or in a language the index does not cover. Try a
distinctive fragment, then fall back to reading the directory the tree suggests.
path: orlanguage:, or quote a longer phrase. Do not page through them.
existed. search_commits for the old name distinguishes those, and the distinction
usually is the answer.
empty layout, which reads as "nothing relevant here".
and the commit history instead of pretending it was read.