sourcegraph-search（源图搜索）

Sourcegraph Code Search Skill

This skill enables autonomous code searching across repositories using the Sourcegraph CLI (src command).

When to Invoke This Skill

Use this skill when you need to:

• Research how features are implemented across codebases
• Find examples of API usage, patterns, or libraries
• Locate specific code patterns (functions, classes, imports)
• Analyze code across repositories (not just local files)
• Search commit history or diffs for changes
• Find security issues or credential leaks
• Understand architecture by searching for patterns
• Answer "where is X used?" questions across projects

Do NOT use for local file searches - use Grep/Glob instead.

Reference Navigation

The reference files are comprehensive. To find specific topics quickly:

# Search reference.md sections
grep -n "^##" references/reference.md

# Find specific filter documentation
grep -n "^### \`repo:" references/reference.md
grep -n "^### \`file:" references/reference.md
grep -n "^### \`lang:" references/reference.md

# Find examples by use case
grep -n "^##" references/examples.md

See reference.md for complete syntax documentation. See examples.md for practical search patterns organized by use case.

Quick Start

Basic Search Syntax

src search 'PATTERN'              # Simple text search
src search -json 'PATTERN'        # JSON output for parsing
src search 'repo:REGEX PATTERN'   # Search specific repos
src search 'lang:go PATTERN'      # Search Go files only

Common Search Patterns

1. Find function/method implementations

src search 'lang:go func handleRequest'
src search 'lang:python def authenticate'

2. Search in specific repository

src search 'repo:github.com/org/repo$ TODO'
src search 'repo:sourcegraph/sourcegraph auth'

3. Search with multiple filters

src search 'repo:kubernetes lang:go file:test fmt.Errorf'
src search 'TODO -file:test -file:spec'

See examples.md for more patterns including file types, commit history, and boolean operators.

Workflow

When searching code:

1. Understand the goal - What pattern? Which repos/languages?
2. Construct the query - Start with pattern, add filters (repo:, lang:, file:), use operators (AND, OR, NOT)
3. Execute - Run src search 'query' or src search -json 'query' for programmatic parsing
4. Parse results - Extract matches, identify patterns, note files for investigation
5. Refine - Too many results? Add filters. Too few? Broaden search.

Key Filters

Most common filters: repo:, lang:, file:, type:, case:, - prefix for exclusion.

See reference.md for complete filter documentation and syntax.

Pattern Types

Sourcegraph supports three pattern types:

1. Literal (default): Exact text matching src search 'func main('
2. Regexp: Use patternType:regexp for regex (RE2 syntax) src search 'patternType:regexp func \w+Handler'
3. Structural: Use patternType:structural for syntax-aware matching src search 'patternType:structural fmt.Sprintf(:[format],:[...])'

See reference.md for complete pattern syntax, regex reference, and structural search details.

CLI Flags

• -json: Output results as JSON (for parsing)
• -stream: Stream results as they arrive
• -display N: Limit displayed results (with -stream)
• --: Separate flags from query (for queries starting with -)

Important Notes

Negation in Queries

Queries starting with negation need -- separator:

src search -- '-repo:foo/bar error'

Use -json for programmatic parsing. Set NO_COLOR=t to disable colors or COLOR=t to force colors when piping.

Default search scope excludes forks and archived repos. Include with fork:yes or archived:yes.

Examples by Use Case

Finding Implementation Examples

# How do people handle authentication in Go?
src search 'lang:go repo:.*auth.* middleware'

# React hooks usage
src search 'lang:typescript repo:facebook/react use.*Hook'

Security Auditing

# Find hardcoded credentials
src search 'patternType:regexp (password|secret|api_key)\s*=\s*["\'][^"\']+["\']'

# Exposed private keys
src search 'type:diff BEGIN.*PRIVATE KEY'

API Research

# How is this library used?
src search 'lang:python import requests'

# Find all GraphQL mutations
src search 'file:\.graphql$ type Mutation'

Refactoring Research

# Find deprecated API usage
src search 'repo:myorg/ oldDeprecatedFunction'

# Find TODO comments in non-test files
src search 'TODO -file:test -file:spec'

Advanced Features

For comprehensive syntax reference, pattern types, and advanced operators, see reference.md.

For more practical examples and complex query patterns, see examples.md.

Troubleshooting

No results?

• Check repository access/permissions
• Verify repository is indexed by Sourcegraph
• Try broader search terms
• Remove restrictive filters

Too many results?

• Add more specific filters
• Use lang: to narrow by language
• Use repo: with regex for specific repositories
• Combine with file: for specific paths

Syntax errors?

• Check regex syntax (RE2 format)
• Quote the entire query
• Use -- before queries starting with -
• Verify filter names are correct

Integration with Other Tools

After finding results with Sourcegraph:

• Use Read tool to examine specific files locally
• Use Grep for more detailed local searching
• Use Bash for git operations on repositories
• Use WebFetch to access repository URLs

Best Practices

1. Start broad, then narrow: Begin with simple patterns, add filters incrementally
2. Use appropriate pattern types: Literal for exact matches, regexp for patterns
3. Combine filters effectively: repo: + lang: + file: for precision
4. Parse JSON for programmatic analysis: Use -json when processing results
5. Respect quotas and limits: Sourcegraph may have rate limits or result limits
6. Cache insights: Remember patterns that work for future searches

Performance Tips

• Specific repo: filters are faster than broad searches
• Language filters (lang:) significantly narrow scope
• File filters (file:) reduce search surface
• Use count: to limit results when you just need examples
• Streaming (-stream) is better for large result sets

Reference Files

• reference.md: Complete syntax documentation, all filters, operators, pattern types
• examples.md: Practical search patterns organized by use case