Reading code like a detective
"When did this behaviour change, and why?" is one of the most useful questions a PM can answer alone. This lesson gives you the tools: how to find your way around an unfamiliar repository, search code across GitHub, follow a line back through blame to its commit, pull request and issue, search history with the pickaxe, and let git bisect find the commit that broke something.
By the end you can
- Orient yourself in a new repository in fifteen minutes: README, scripts, entry points, folders
- Write GitHub code search queries that answer real product questions
- Trace a line from
git blameto the commit, the PR and the issue, skipping formatting commits - Find when a string or pattern appeared or disappeared with
git log -S,-Gand-L - Run
git bisect runwith a small check script to find the commit that broke a behaviour
The everyday picture
The month-end stock count at a store shows 40 fewer cartons of detergent than the system says. Nobody shouts. The inventory controller follows the paper trail. She pulls the goods received notes (GRNs) for that product and checks the quantity received against the supplier's delivery note. Then the transfer notes to other stores, then the damage write-offs, and the sales. Day by day she narrows it down until she finds it: on the 14th, a GRN was entered as 4 cartons instead of 44. The GRN has the receiver's name and the delivery number, so she can ask exactly the right person exactly the right question.
Code has the same paper trail. Every line was put there by a commit, every commit has an author, a date and a message, and on a well-run team every commit came from a pull request that links to an issue. Blame, the pickaxe and bisect are how you follow that trail, the way she followed the GRNs.
Getting your bearings in an unfamiliar repository
Before tracing anything, spend fifteen minutes getting the map. In order:
- README and docs folder: what the project is, how to run it, and often an architecture section. A missing or stale README is your first finding.
package.json: thescriptstell you how the team works (dev,test,build,migrate), anddependenciestell you the stack:@nestjs/coremeans NestJS,@prisma/clientmeans Prisma,react-nativemeans a mobile app (see Node.js and npm).- Entry points: where the program starts. For a NestJS API,
src/main.tsand the modules it imports (see From script to service); for a React Native app,index.jsand the navigator; for a script, themainfield. - Folder names: in a NestJS API, folders under
src/are usually features (sales,grn,pricing). Feature names are your search terms. .github/: workflows show how code is tested and deployed (see GitHub Actions: continuous integration), CODEOWNERS shows who owns what (see Pull requests and code review).- Tests: the clearest description of intended behaviour. A test named "applies FEST10 only when quantity is 3 or more" is a business rule written down.
In VS Code, four commands do most of the navigating (see VS Code essentials). Go to Definition (F12) jumps to where a function is defined. Find All References (Shift+Alt+F12 on Windows, Shift+Option+F12 on macOS) lists every place that calls it, which answers "if we change this, what else is affected?". Show Call Hierarchy (Shift+Alt+H, macOS Shift+Option+H) shows the chain of callers, for example from the HTTP controller down to the VAT function. And Go to Symbol in Workspace (Ctrl+T, macOS Cmd+T) finds any function by name. The Timeline view at the bottom of the Explorer shows the commits that touched the open file, and the command "Git: Toggle Git Blame Editor Decoration" shows blame next to each line.
Quick check
You open an unfamiliar Node repository. Which single file tells you fastest how the team runs its tests, builds and migrations?
The scripts section is the team's list of everyday commands. The lockfile pins exact dependency versions but says nothing about how the team works, and .gitignore only lists files Git should not track.