A gem is misbehaving and the docs don’t cover your case. You clone it, open the source, and there are 340 files. The instinct is to start at the top of the directory listing and read. Don’t — you’ll spend two hours and learn the shape of the file tree. There’s a faster route, and it starts from the outside rather than the inside.

Start From the Public Interface

You already know one thing about this codebase: the line of your code that calls into it. That’s the entry point, and everything you need is reachable from there.

Example:

# Your code
Faraday.new(url: "https://api.example.com") do |f|
  f.request :json
  f.adapter :net_http
end

Three questions, in order:

1. Where is Faraday.new defined?
2. What does the block parameter f actually receive?
3. Where does :net_http get resolved into a class?

Answer those and you understand the architecture. You do not need to read the retry middleware.

Example:

# In the gem's source
rg "def self\.new" lib/faraday.rb
rg "def request\b" lib/faraday/
rg "register_middleware|:net_http" lib/

Ask the Runtime, Not the Filesystem

Faster than any amount of grepping, and it accounts for metaprogramming that grep can’t see.

Example:

# In a console with the gem loaded
conn = Faraday.new(url: "https://example.com")

conn.method(:get).source_location
# => ["/gems/faraday-2.9.0/lib/faraday/connection.rb", 174]

conn.method(:get).owner
# => Faraday::Connection

Faraday::Connection.instance_method(:get).source_location
conn.class.ancestors.first(8)

Walk the whole override chain when a method has been patched by several layers:

m = conn.method(:run_request)
while m
  puts "#{m.owner.to_s.ljust(40)} #{m.source_location&.join(':')}"
  m = m.super_method
end

That loop shows you every module contributing to one method, in resolution order. It takes four seconds and replaces an hour of reading.

Find where something got defined at runtime

When source_location returns nil, the method was generated. TracePoint on :call filtered to that method name will tell you, or check the gem’s define_method calls:

rg "define_method|class_eval|instance_variable_set" lib/ | head -20

Read the Tests Before the Source

The best documentation in any repository is its test suite, because tests are executable examples that are guaranteed to be current.

Example:

ls spec/          # or test/
rg -l "your_feature" spec/

Tests tell you three things the source doesn’t:

• The intended usage — the public API as its authors imagine it being called
• The edge cases — what the authors knew could go wrong
• What’s actually supported — a code path with no test is a code path nobody guaranteed

For a specific behaviour, find its test first. It’s usually 15 lines and shows the setup, the call, and the expectation — a complete, runnable example of the thing you’re trying to understand.

Let Git Tell You the Story

Example:

# Who wrote this line, and why
git log -1 -L 47,52:lib/faraday/connection.rb

# Every commit touching this file, newest first
git log --oneline -- lib/faraday/connection.rb | head -20

# Find the commit that introduced a string
git log -S "idempotency_key" --oneline

# Find when a line was changed to its current form
git log -p -S "retry_after" -- lib/

git log -S (the “pickaxe”) is the one people don’t know. It searches for commits where the count of a string changed, which finds the commit that introduced a feature rather than the ones that reformatted around it. The commit message on that commit is often the design rationale you were looking for.

The blame-through-refactors trick

git log --follow -p -- lib/faraday/connection.rb
git blame -w -C -C -L 40,60 lib/faraday/connection.rb

-w ignores whitespace, -C -C follows code moved between files. Without those, blame on a refactored file just tells you who ran the formatter.

Map the Architecture in Ten Minutes

Before diving in, build a rough model.

Example:

# What's the shape and where's the weight?
tokei lib/          # or: find lib -name '*.rb' | xargs wc -l | sort -rn | head -20

# Directory structure, two levels
tree -L 2 lib/

# The entry point — what does the gem require?
cat lib/faraday.rb

# Public API surface
rg "^\s*def [a-z]" lib/ --stats | tail -5

The biggest files are usually the core; the smallest are usually configuration or value objects. lib/<gemname>.rb is the manifest — it requires everything in dependency order, which is itself a map.

Then the documents:

cat README.md | head -100
ls docs/ CHANGELOG.md UPGRADING.md ARCHITECTURE.md 2>/dev/null

ARCHITECTURE.md is rare and gold when present. CHANGELOG.md tells you what’s been changing recently — active areas are where the bugs are.

Follow One Path All the Way Down

The mistake is breadth-first reading. Go depth-first on a single realistic operation and ignore everything you pass.

Pick the thing you actually care about — “what happens when a request times out” — and trace only that:

Example:

require "debug"

conn = Faraday.new(url: "https://httpbin.org/delay/10") do |f|
  f.options.timeout = 1
end

binding.break
conn.get("/")

(rdbg) catch Faraday::TimeoutError
(rdbg) continue

The debugger stops at the raise site with the full stack. Now you know exactly which file raises, what called it, and what state it had — without reading a single unrelated file.

Pro-Tip: Make a scratch fork and add puts statements liberally — then throw it away. There’s a persistent reluctance to modify a dependency’s source, so people read instead, which is much slower. bundle open faraday opens the installed gem in your editor and you can edit it directly; gem pristine faraday restores it when you’re done. Ten puts statements showing which branch executed and what the values were will teach you more in five minutes than an hour of careful reading, because you’re getting ground truth about the path your input actually takes rather than reconstructing all possible paths in your head. For a longer investigation, clone the repo and point your Gemfile at it with path: so you can commit experiments and diff them.

Contributing Back

If you found a bug, the path from understanding to patch is shorter than it looks.

1. Find the test file for the area — you already located it
2. Write a failing test reproducing your case, in their style
3. Fix it, in the smallest possible diff
4. Check CONTRIBUTING.md for their process before opening anything

A PR containing a failing test plus a two-line fix gets merged. A PR containing a refactor plus a fix gets a discussion. Maintainers are reviewing in their spare time; make the review trivial.

Open an issue first for anything that isn’t obviously a bug — “I think X is wrong, here’s a reproduction, happy to PR” respects their time and avoids you building something they’d reject on design grounds.

Conclusion

Enter from the line of your own code that calls in, not from the top of the directory tree. Ask the runtime where methods live with source_location and super_method rather than grepping, since that also handles metaprogramming. Read the tests for the behaviour you care about — they’re current, executable, and short. Use git log -S to find the commit that introduced something and read its message for the rationale. Then trace one realistic operation end to end with a debugger or throwaway puts statements, and ignore everything you pass on the way. Understanding a codebase is depth-first; breadth-first is how you spend an afternoon learning a file tree.

FAQs

Q1: How do I open the source of an installed gem?
bundle open <gemname> opens it in $EDITOR. bundle show <gemname> prints the path. gem pristine <gemname> undoes any edits you made.

Q2: What if the code is heavily metaprogrammed and grep finds nothing?
Use the runtime: method(:name).source_location and owner, plus ancestors to see the full chain. TracePoint on :call catches definitions grep can’t.

Q3: Should I read the whole codebase before contributing?
No. Understand the area you’re touching and its tests. Nobody who has contributed to Rails has read Rails.

Q4: How do I tell whether a project is worth depending on?
Recent commit activity, open issues with maintainer replies, a CI badge that’s green, a changelog, and a test suite you can run locally. Absence of the last two is the strongest signal to be cautious.

Q5: The maintainer hasn’t responded to my PR in a month. Now what?
Bump it politely once. If the project is genuinely dormant, fork it and depend on your fork via git: in the Gemfile — and say so in a comment so the next person on your team knows why.