Searching Sourcegraph

Searching Sourcegraph

Search before you build. Existing patterns reduce tokens, ensure consistency, and surface tested solutions.

Tool Selection Logic

Start here:

1. Know the exact symbol or pattern? → keyword_search 2. Know the concept, not the code? → nls_search 3. Need to understand how/why? → deepsearch → deepsearch_read 4. Tracing a symbol's usage? → find_references 5. Need full implementation? → go_to_definition → read_file 6. Need to know what repos a user has worked on? → get_contributor_repos

Scoping (Always Do This)

repo:^github.com/ORG/REPO$           # Exact repo (preferred)
repo:github.com/ORG/                 # All repos in org
file:.*\.ts$                         # TypeScript only
file:src/api/                        # Specific directory
file:.*\.test\.ts$ -file:__mocks__   # Tests, exclude mocks

Start narrow. Expand only if results are empty.

Combine filters: repo:^github.com/myorg/backend$ file:src/handlers lang:typescript

Context-Aware Behaviour

When the user provides a file path or error message:

• Extract symbols, function names, or error codes
• Search for those exact terms first
• Trace references if the error involves a known symbol

When the user asks "how does X work":

• Use deepsearch to initiate the search, then deepsearch_read to retrieve results
• Follow up with read_file on key files mentioned in the response

When the user asks who worked on something or what repos a contributor has touched:

• Use get_contributor_repos with one or more usernames to discover their active repositories
• Then scope subsequent searches to those repos

When the user is implementing a new feature:

• Search for similar existing implementations first
• Read tests for usage examples
• Check for shared utilities before creating new ones

When troubleshooting an error, build failure, or runtime exception:

• Extract exact symbols, error codes, or log lines from the stack trace or build output
• Search for the error site, then trace the full call chain with find_references
• Check recent changes with diff_search and commit_search early — regressions are common
• Identify all affected code paths and services before proposing a fix

When fixing a bug:

• Extract exact symbols from the error message or stack trace
• Search for the error site, then trace the full call chain with find_references
• Check recent changes with diff_search and commit_search early — regressions are common
• Find all affected code paths before writing the fix
• Read existing tests to understand intended behaviour

Workflows

For detailed step-by-step workflows, see:

• workflows/implementing-feature.md — when building new features
• workflows/understanding-code.md — when exploring unfamiliar systems
• workflows/debugging-issue.md — when troubleshooting errors, build failures, stack traces, support issues, or runtime exceptions
• workflows/fixing-bug.md — when fixing bugs with extensive Sourcegraph search
• workflows/code-review.md — when reviewing a pull request or changeset

Efficiency Rules

Minimise tool calls:

• Chain searches logically: search → read → references → definition
• Don't re-search for the same pattern; use results from prior calls
• Prefer keyword_search over nls_search when you have exact terms (faster, more precise)

Batch your understanding:

• Read 2-3 related files before synthesising, rather than reading one and asking questions
• Use deepsearch + deepsearch_read for "how does X work" instead of multiple keyword searches

Avoid common token waste:

• Don't search all repos when you know the target repo
• Don't use deepsearch for simple "find all" queries — keyword_search is faster
• Don't re-read files you've already seen in this conversation

Query Patterns

For more patterns, see query-patterns.md.

Output Formatting

Search results:

• Present as a brief summary, not raw tool output
• Highlight the most relevant file and line
• Include a code snippet only if it directly answers the question

Code explanations:

• Start with a one-sentence summary
• Use the codebase's own terminology
• Reference specific files and functions

Recommendations:

• Present as numbered steps if actionable
• Link to specific patterns found in the codebase
• Note any existing utilities that should be reused

Common Mistakes

Principles

• Start narrow, expand if needed
• Chain tools: search → read → find references → definition
• Check tests for usage examples
• Read before generating

Common Search Examples

Real-world search examples for common tasks.

Finding Implementations

"Where is authentication handled?"

nls_search: "repo:^github.com/org/repo$ authentication middleware validation"

"How do we make API calls?"

keyword_search: "repo:^github.com/org/repo$ fetch\|axios\|http\.request"

"Find all database queries"

keyword_search: "repo:^github.com/org/repo$ \.query\(\|\.execute\("

Understanding Flow

"How does user signup work end-to-end?"

deepsearch_read: "Trace the user signup flow from form submission to database creation"

"What happens when a payment fails?"

deepsearch_read: "How does the system handle failed payment attempts?"

Debugging

"Find where this error is thrown"

keyword_search: "repo:^github.com/org/repo$ 'User not found'"
find_references: Find all usages of the error constant

"What changed in authentication recently?"

diff_search: repos=["github.com/org/repo"] pattern="auth" after="2 weeks ago"

Finding Patterns

"How do other features handle validation?"

nls_search: "repo:^github.com/org/repo$ input validation schema"

"Find examples of pagination"

keyword_search: "repo:^github.com/org/repo$ offset\|limit\|cursor\|pageToken"

Tracing Dependencies

"What uses this utility function?"

find_references: repo="github.com/org/repo" path="src/utils/format.ts" symbol="formatDate"

"Where is this type defined?"

go_to_definition: repo="github.com/org/repo" path="src/api/handler.ts" symbol="UserResponse"

Query Patterns Reference

Common regex patterns for Sourcegraph searches.

Language-Specific Patterns

TypeScript/JavaScript

Python

Go

Project Structure Patterns

Common Search Scopes

# Single repo
repo:^github.com/org/repo$

# All repos in org
repo:github.com/myorg/

# Specific file types
file:.*\.ts$ lang:typescript

# Specific directories
file:src/api/ file:.*\.ts$

# Exclude patterns
file:.*\.ts$ -file:.*\.test\.ts$ -file:__mocks__

# Multiple file types
file:\.(ts|tsx|js|jsx)$

Tips

• Use \| for OR in regex patterns
• Use ^ and $ for exact repo matching
• Escape special regex chars: \. \( \)
• Combine file: and repo: for precise scoping

Code Review

When reviewing a pull request or changeset, use Sourcegraph MCP to verify correctness, spot risks, and check consistency — before leaving comments.

Checklist

Task Progress:
- [ ] Understand the scope of changes
- [ ] Verify changed code against existing patterns
- [ ] Check for similar prior implementations or fixes
- [ ] Trace impact on callers and dependents
- [ ] Review test coverage
- [ ] Inspect recent changes in the same area
- [ ] Flag inconsistencies or missing conventions

Steps

1. Understand the Scope of Changes

Start by reading the diff or changed files to extract the key symbols, functions, and modules being modified.

Collect:

• New or modified function/class names
• Files touched
• Any new dependencies or imports introduced
• Error handling paths added or changed

2. Verify Against Existing Patterns

Check that the new code follows established conventions in the codebase:

nls_search: "repo:^github.com/org/repo$ how is <concept> typically implemented"
keyword_search: "repo:^github.com/org/repo$ file:src/<area>/ <pattern or function name>"

Look for:

• Naming style (snake_case vs camelCase, verb prefixes, etc.)
• File organisation conventions
• How similar functionality is already implemented elsewhere
• Whether shared utilities exist that should be reused

read_file: <2-3 representative files from the same area>

3. Search for Prior Art on the Same Problem

Confirm the approach isn't reinventing something already solved:

nls_search: "repo:^github.com/org/repo$ <feature or problem the PR solves>"
commit_search: repos=["org/repo"] messageTerms=["<keyword related to the change>"]

If a similar feature exists, compare the approaches and flag divergence if it reduces consistency.

4. Trace Impact on Callers and Dependents

For any modified public symbol (function, type, constant), check its usage:

find_references: <modified function or type>

Verify:

• All call sites are compatible with the new signature or behaviour
• No implicit contracts are broken (return value shape, error semantics, etc.)
• If a shared utility is changed, all consumers are safe

For deeper impact analysis:

deepsearch_read: "How is <changed component> used across the system?"

5. Review Test Coverage

Read the existing tests for the affected area:

keyword_search: "repo:^github.com/org/repo$ file:.*\.test\. <function or module name>"
read_file: <relevant test files>

Check:

• Are the new code paths covered?
• Do existing tests still match the updated behaviour?
• Are edge cases (empty inputs, errors, boundary values) tested?
• Are tests missing for non-trivial logic introduced in the PR?

6. Inspect Recent Changes in the Same Area

Recent activity reveals context and potential conflicts:

diff_search: "repo:^github.com/org/repo$ <file path or function name>"
commit_search: repos=["org/repo"] messageTerms=["<area keyword>"]

Use compare_revisions to see what changed in the area recently:

compare_revisions: repo="org/repo" base="main~30" head="main" path="src/<affected area>/"

Look for:

• Parallel changes that could conflict
• Recent fixes the PR might accidentally revert
• Patterns established in nearby recent work

7. Flag Inconsistencies and Missing Conventions

After searching, compile review comments around:

• Pattern divergence: Code that works but differs from established style without reason
• Missing reuse: New helpers that duplicate existing utilities
• Untested paths: Non-trivial logic without coverage
• Broken contracts: Changed behaviour that affects undiscovered callers
• Risk surface: Error handling gaps, missing validation, or unsafe assumptions

Tips

• Search before commenting — many apparent issues are intentional deviations with prior art
• Use find_references before flagging a changed signature as breaking; verify actual impact
• Read tests first — they often clarify the intended contract faster than the implementation
• Check recent commits in the same path; the PR may be part of a larger sequence of changes
• Use deepsearch_read when the change touches a system you're unfamiliar with before reviewing it
• Scope searches to the affected directory or module to reduce noise

Troubleshooting Issues

When investigating errors, build failures, stack traces, support issues, or runtime exceptions in production, search systematically from symptom to root cause.

Checklist

Task Progress:
- [ ] Collect symptoms (error, stack trace, logs)
- [ ] Search for the error message or code
- [ ] Find where the error originates
- [ ] Understand the context and conditions
- [ ] Check recent changes for regressions
- [ ] Identify impact and affected paths

Steps

1. Collect Symptoms

Before searching, extract all available signal:

• Exact error message or exception text
• Stack trace symbols (function names, file paths, line numbers)
• Error codes, constants, or exit codes
• Build output or log lines near the failure
• Environment details (service name, version, deployment context)

The more precise your search terms, the fewer tool calls you need.

2. Search for the Error

keyword_search: "repo:X 'ExactErrorMessageHere'"

Search for:

• Exact error message text or substrings
• Exception class names or error constants
• Log message patterns near the failure
• Build task names or compiler error codes

keyword_search: "repo:X ErrBuildFailed"
nls_search: "repo:X compilation failure during asset bundling"

Run multiple searches in parallel when you have several candidate terms.

3. Find Where It Originates

find_references: <error symbol or throwing function>

Locate all sites that produce this error:

• Direct throw / panic / return err statements
• Build scripts or CI steps that emit the failure
• Middleware or interceptors that wrap errors
• Error factory functions

Read each throw site with read_file to understand the exact trigger condition.

4. Understand the Context

deepsearch_read: "When does <error> occur and what are the expected conditions?"

Get a deeper understanding of:

• Conditions that trigger the error or failure
• Expected handling or recovery patterns
• Related error types or failure modes
• How this path behaves under normal operation

5. Check Recent Changes

Recent commits are the most common source of regressions:

diff_search: "repo:X <function or symbol name>"
commit_search: repos=["org/repo"] messageTerms=["keyword related to failure area"]

Use compare_revisions to diff a specific before/after window:

compare_revisions: repo="org/repo" base="main~30" head="main" path="src/affected/"

6. Identify Impact and Affected Paths

Check how broadly the issue affects the system:

find_references: <the failing function or error symbol>
keyword_search: "repo:X <shared utility involved in the failure>"

Confirm whether:

• Other callers or services are affected
• The same failure can surface in other environments (staging, canary)
• There are existing error handling paths that should have caught this

Tips

• Extract exact symbols from stack traces — they are the fastest search terms
• Build failures often reference a specific task, target, or step name — search for that
• Errors frequently have multiple throw sites; always use find_references to find all of them
• Recent diffs narrow suspects dramatically — check them early
• For runtime exceptions in production, search for the error constant and its callers before looking at logs
• Use deepsearch_read when the failure spans multiple layers and you need architectural context

Fixing a Bug

When fixing bugs, use Sourcegraph MCP to extensively search for the root cause before touching any code.

Checklist

Task Progress:
- [ ] Reproduce and extract symptoms
- [ ] Search for error / failure site
- [ ] Trace the call chain
- [ ] Find all affected code paths
- [ ] Check recent changes
- [ ] Understand the intended behaviour
- [ ] Validate the fix against similar patterns

Steps

1. Extract Symptoms

Before searching, collect everything available from the bug report:

• Exact error message or log line
• Stack trace symbols (function names, file paths, line numbers)
• Error codes or constants
• Relevant request/response data

The more precise your search terms, the fewer tool calls you need.

2. Search for the Error Site

keyword_search: "repo:^github.com/org/repo$ 'ExactErrorMessageHere'"

Also search for:

• The error class or constant name
• Any unique string from the stack trace
• Log statement nearest the failure

keyword_search: "repo:X file:src/ ErrTokenExpired"
nls_search: "repo:X token validation failure handling"

Run multiple searches in parallel when you have several candidate terms.

3. Find Where the Error Originates

find_references: <error symbol or throwing function>

Locate every site that can produce this error:

• Direct throw / panic / return err statements
• Error factory functions
• Middleware or interceptors that wrap errors

Read each throw site with read_file to understand the exact condition.

4. Trace the Full Call Chain

go_to_definition: <function at the throw site>
find_references: <caller of that function>

Walk the chain upward until you reach the entry point (HTTP handler, queue consumer, CLI command, etc.).

For complex chains, use:

deepsearch_read: "How does the X flow work from entry point to error site?"

5. Find All Affected Code Paths

Bugs often affect more than one path. Search broadly:

keyword_search: "repo:X <shared utility or function involved>"
find_references: <the function being fixed>

Confirm whether:

• Other callers rely on the current (buggy) behaviour
• Tests exist that cover these paths
• The same bug can surface elsewhere

6. Check Recent Changes

Recent commits are the most common source of regressions:

diff_search: "repo:X <function or symbol name>"
commit_search: repos=["org/repo"] messageTerms=["keyword related to bug area"]

Use compare_revisions if you want to diff a specific before/after window:

compare_revisions: repo="org/repo" base="main~30" head="main" path="src/auth/"

7. Understand the Intended Behaviour

Before writing the fix, confirm what correct behaviour looks like:

nls_search: "repo:X how should <feature> behave when <condition>"
read_file: <relevant test files>

Read existing tests to understand invariants. If tests are missing, that is part of the bug.

8. Find a Reference Fix or Pattern

Search for similar bugs that were already fixed in the codebase:

commit_search: repos=["org/repo"] messageTerms=["fix", "bug keyword"]
nls_search: "repo:X handle <edge case similar to the bug>"

Match your fix to the established pattern so it stays consistent with the codebase.

Tips

• Search extensively before writing a single line of code — most fix time should be spent understanding, not coding
• Never assume the first throw site is the only one; always use find_references
• Check tests first: a failing test often tells you more than the code does
• Recent diffs narrow suspects dramatically — check them early
• If keyword_search returns too many results, scope with file: or lang: filters
• Use deepsearch_read when the bug spans multiple layers and you need architectural context

Implementing a Feature

When building new features, search for similar patterns first to ensure consistency.

Checklist

Task Progress:
- [ ] Find similar implementations
- [ ] Read file structure
- [ ] Study a good example
- [ ] Check shared utilities

Steps

1. Find Similar Implementations

nls_search: "repo:^github.com/org/repo$ user settings CRUD"

Look for features that solve similar problems. Note the patterns used.

2. Explore File Structure

keyword_search: "repo:^github.com/org/repo$ file:src/features/ index.ts"

Understand how features are organised in this codebase.

3. Study a Representative Example

read_file: Read 2-3 files from a well-implemented similar feature

Pay attention to:

• Naming conventions
• File organisation
• Import patterns
• Error handling approach

4. Check for Shared Utilities

find_references: Trace usage of common utilities

Before creating new helpers, check if reusable utilities exist:

• Validation functions
• API wrappers
• UI components
• Type definitions

Tips

• Don't create new patterns when existing ones work
• Match the style of surrounding code
• Check tests for usage examples of utilities
• Look at recent PRs for similar features

Understanding Unfamiliar Code

When exploring systems you don't know, start broad and narrow down.

Checklist

Task Progress:
- [ ] Get big picture via Deep Search
- [ ] Find entry points
- [ ] Trace implementation
- [ ] Review related tests

Steps

1. Get the Big Picture

deepsearch_read: "How does order fulfillment work in this codebase?"

Deep Search provides architectural understanding. Ask "how" and "why" questions.

2. Find Entry Points

keyword_search: "repo:X file:src/routes export.*order"

Look for:

• API route handlers
• Event listeners
• CLI commands
• UI component entry points

3. Trace the Implementation

go_to_definition: Jump to main handler
find_references: See how it's used

Follow the code path from entry point through business logic.

4. Review Related Tests

keyword_search: "repo:X file:.*\.test\.ts describe.*order"

Tests reveal:

• Expected behaviour
• Edge cases
• Usage patterns
• Integration points

Tips

• Read 2-3 related files before synthesising
• Tests are documentation—read them
• Check for architecture docs in docs/ or README files