Cross-repository code navigation

Remember back when you were learning data structures for the first time (if you didn't, this will make sense either way) and the topic of graphs came up? The visualization of these graphs was incredibly easy to understand, but then came the actual coding of the data structure. How did each node talk to eachother? I see they clearly do in the image?! Then once you got the hang of it, it became one of the most used data structures in your arsenal? Well, you're in luck, we're not teaching a new data structure today, but we will show you how easy it can be to have nodes (repos) connect and be easily visualized. As well as how you can search one repository for a reference in another in milliseconds.

Debugging an exception in a shared library requires navigating to its source code. Understanding how teams use your API means finding every caller across repositories. Tracking which services need updates after a security patch demands visibility into dependency usage.

Cross-repository code navigation solves these problems. Click on an imported symbol and jump directly to its definition in another repository. See every caller of a function, regardless of which repository they're in. Or, follow dependency chains with precision across your entire codebase using Sourcegraph.

In this article, we touch upon:

1. What cross-repository search is.
2. How Sourcegraph works under the hood to get you accurate results.
3. Dive deeper into the technology behind those accurate results.
4. Walk you through getting set up.
5. Provide a few code examples to get you up and running.

What is cross-repository search

Two common types of search

Task	Multi-Repo Search	Cross-Repo Search
Find text pattern	Yes	Yes
Find semantic references	No	Yes
Understand symbols across repos	No	Yes

Cross-repo search (or code navigation, we'll use that interchangeably in this blog) provides semantic code understanding across repositories. It tracks relationships across repository boundaries. Multi-repo text search performs pattern matching across repositories. It finds every occurrence of a string or regex pattern.

The key difference is text versus meaning. Text search returns matches based on character sequences. Cross-repo navigation understands what code references. It's capable of understanding which repository owns a symbol and which version of a dependency you're using.

Why this is difficult

Challenge 1: The same function name can exist in multiple repositories.

The search system needs to identify which specific implementation you're referencing when your code imports a function. This requires tracking both the package name and version as part of the symbol's identity.

Challenge 2: Code in repository A frequently references code defined in repository B.

The search system must resolve these relationships accurately. Text matching cannot determine that an import statement in one repository corresponds to a specific definition in another repository.

Challenge 3: Navigating to a symbol's definition requires knowing which version the calling code is using.

The search system must track version information for every symbol to route you to the correct implementation.

When you need this

• When debugging requires navigating from an import statement to the actual implementation in another repository. Without a system that enables cross-repository search, you'd end up spending hours, Ctrl + f-ing into hundreds of folders.
• Impact analysis demands finding all semantic usages of a function before making breaking changes. Without a system that enables cross-repository search, your team would be stuck in analysis paralysis.
• Dependency upgrades involve comparing implementations across different versions to understand what changed. Without a system that enables cross-repository search, production-level code pushed without checking dependencies would potentially break your application or service.

Cross-repository is not magic, even though we all wish there was a way to wave a wand and get exactly what your brain is conjuring. Although LLMs feel like magic, there's a lot that goes on behind the scenes. Choosing a tool specifically defined for this compiler-level code understanding often outperforms current generic agents/LLMs. How is that powered? That's where SCIP comes in.

How SCIP enables semantic code understanding across repo boundaries

What is SCIP?

SCIP (Source Code Intelligence Protocol) provides a language-agnostic indexing format that captures semantic information about code. Created by Sourcegraph (us), SCIP replaced the older LSIF (Language Server Index Format) with a more efficient and flexible design.

What SCIP indexes contain

SCIP indexes store structured data about your code in two main categories.

Symbols contain definition information:

• Definition location (file path, line number, column number)
• Symbol metadata (whether it's a function, class, variable, etc.)
• Package ownership (which repository and version defines this symbol)

External Symbols track cross-repository dependencies:

• Symbols defined in other packages
• Cross-repository dependency information
• Version data for each dependency

We'll show you exactly how this works from a front-end perspective later in this blog!

You've indexed, now navigate

When you click "Go to Definition" on an imported function, Sourcegraph uses the SCIP index to resolve the reference.

The resolution process works as follows:

1. Sourcegraph identifies the symbol
2. Looks up the symbol ID in the SCIP index
3. The index contains the package name and version for that symbol
4. Resolves to the repository containing that package and version
5. Returns the exact file path and line number
6. Navigates directly to the definition

This differs from text search in several ways. There is no pattern matching. The system performs a direct lookup using the symbol's unique identifier. Results are compiler-accurate because the indexer analyzed the code semantically. Version-aware resolution ensures you navigate to the correct implementation for the version your code depends on.

SCIP as an open protocol

Sourcegraph provides CLI tools for working with SCIP indexes, including commands like scip snapshot for visualizing index data and scip print for inspecting index contents.

SCIP provides the foundation for cross-repository navigation. The next section examines how SCIP handles the hardest technical challenges: forward declarations, namespace handling, and dependency graph indexing.

Diving deeper: How SCIP tracks symbols across repos

One thing to note while you test sourcegraph.com/search is that SCIP is done all in the background. When you search or navigate code in Sourcegraph, SCIP indexes provide the semantic data that makes cross-repository navigation possible. Each symbol in your codebase gets a unique identifier that includes three components:

• The package name
• The version
• The symbol name.

This structure allows Sourcegraph to resolve references accurately, even when the definition exists in a completely different repository.

The forward declaration problem

Forward declarations create a technical challenge for cross-repository indexing. A forward declaration references a symbol without specifying which package defines it. The SCIP indexer must analyze all the code, including dependencies, to discover where the actual definition lives. This requires indexing every library you depend on.

Indexing cost scales with the depth of your dependency graph. The benefit is compiler-accurate navigation across any number of repositories. When you use "Find References" on a symbol, Sourcegraph returns every semantic usage across all repositories, not just text matches.

Cross-repo search examples in Sourcegraph

Combining text search with under-the-hood SCIP-powered navigation creates powerful workflows for managing dependencies and understanding code relationships.

*Note**: These are generic queries to help you structure your search tactics. Insert your own libraries and packages to get the most out of Sourcegraph.*

Finding All Usages of a Dependency:

context:global file:package.json "your-internal-lib":\s*"[~^]?1\.2\.3" patterntype:regexp

This query finds every repository using version 1.2.3 of your internal library.

Verifying Dependency Upgrades:

context:global file:package.json "your-internal-lib":\s*"[~^]?(1\.2\.[4-9]|1\.[3-9]\.|[2-9]\.)" patterntype:regexp

This confirms which repositories have upgraded to newer versions.

Security Vulnerability Remediation:

bash

# Step 1: Find vulnerable package versions

context:global file:package.json "lodash":\s*"[~^]?4\.17\.19" patterntype:regexp

# Step 2: Verify patched versions after upgrade

context:global file:package.json "lodash":\s*"[~^]?(4\.17\.[2-9][0-9]|4\.[2-9][0-9]\.|[5-9]\.)" patterntype:regexp

# Step 3: Confirm zero results for vulnerable versions

context:global file:package.json "lodash":\s*"[~^]?4\.17\.19" patterntype:regexp

The first query identifies vulnerable instances. The second query finds patched versions. If the third query returns zero results, remediation is complete.

Code navigation enhances these searches. After finding results, click on any symbol in the dependency files. Sourcegraph uses SCIP to navigate to definitions, even when they exist in other repositories. This combines the breadth of text search with the precision of semantic code understanding.

How auto-indexing enables this in Sourcegraph

Auto-indexing runs the SCIP indexing process automatically for your repositories. Sourcegraph clones your repositories into isolated executors, which are sandboxed environments designed for running resource-intensive tasks. Language-specific indexers like scip-typescript, scip-python, or scip-java analyze your code and generate SCIP index files. These indexes include package and version metadata for every symbol.

The Sourcegraph UI surfaces this data through several features. Search results include "Go to Definition" and "Find References" links that work across repository boundaries. Navigation resolves symbols to their definitions using version-aware lookups. You get real-time code intelligence without configuring local development environments or manually tracking dependency versions.

Understanding how SCIP works behind the scenes helps when configuring auto-indexing. The next section walks through setting up cross-repository navigation in Sourcegraph for your GitHub, GitLab, or Bitbucket repositories.

Trying cross-repository navigation on Sourcegraph public code

Sourcegraph.com hosts over 2.8 million public repositories, with more than 45,000 repositories that have SCIP indexes and precise code navigation enabled. So finding what you need should be fairly quick and simple!

Using simple search

Text search and code navigation work together in Sourcegraph's interface. Take a simple text search query straight from our search UI, like context: global tool.

With no setup, it will return all mentions of "tool" in every public repository and all mentions of it in code.

When you click on an import statement for tool in any repo, Sourcegraph uses the SCIP index to look up the symbol ID and navigate directly to the definition, regardless of which repository contains it.

Using "Go to definition" across repositories

Cross-repository navigation works by following symbols from one repository to their definitions in another. Diving deeper into our previous code example for finding the "tool" keyword, you can navigate through repositories more easily and, with just a click, find the actual definition of that library or function.

Click on any result file that uses this function. When you click on the Tool symbol, a code intelligence panel appears. Select "Go to Definition" from the options.

You jump from application code to the library's source code automatically. The navigation lands on the exact line where the symbol is defined, even though it exists in a completely different repository.

Using "Find References" to See Cross-Repo Usage

The "Find References" feature shows where symbols are used across multiple repositories. Navigate to a popular open-source library and find a commonly used function or class. Click on the symbol to open the code intelligence panel, then select "Find References."

Sourcegraph displays every usage of that symbol across different repositories. The results reveal how many projects depend on this symbol, real-world usage patterns, and the dependency relationships between repositories. This view is particularly useful for library maintainers who need to understand the impact of API changes.

Practical cross-repo search examples

Text search and code navigation work together to enable powerful exploration workflows. You can combine search queries with navigation features to understand code relationships.

Tracking Library Usage:

context:global lang:typescript import.*from.*'react' patterntype:regexp

This query finds TypeScript projects importing React. Click into the results and navigate to see which versions and features different projects use.

Understanding API Implementations:

context:global class.*extends.*Component patterntype:regexp

This finds component implementations across repositories. Click on class names to navigate through inheritance chains, even when base classes are defined in other repositories.

Following Dependency Chains: Search for code in one repository, click on imported symbols, and follow the navigation through multiple dependencies. This helps you understand how different packages connect and depend on each other across the ecosystem.

Enabling this for your own code

Cross-repository navigation requires SCIP indexing for your repositories. You have two options for setting this up.

Auto-indexing is available with Sourcegraph Enterprise. Enable auto-indexing policies in your Sourcegraph instance, and Sourcegraph automatically generates and uploads SCIP indexes for your repositories. This requires no changes to your CI/CD pipelines.

Manual indexing via CI/CD gives you more control over the indexing process. Add SCIP indexers to your continuous integration pipeline and configure them to upload indexes to your Sourcegraph instance after each build. This approach works with both self-hosted and cloud Sourcegraph instances.

Language support includes TypeScript, JavaScript, Python, Go, Java, Scala, Kotlin, and C/C++. Each language has a dedicated indexer that understands its module system and dependency resolution. See the Sourcegraph code navigation documentation for language-specific setup guides and configuration examples.

Cross-repository navigation enables powerful workflows beyond basic code exploration. The next section demonstrates real-world use cases for debugging, dependency management, and impact analysis.

How Sourcegraph's other capabilities enhance cross-repository search

Cross-repository search is powerful for finding exact matches and patterns, but what about finding code by intent rather than syntax?

Deep Search is yet another way Sourcegraph differentiates itself in the repository search game. Deep Search extends cross-repository capabilities with AI-powered semantic understanding. You can ask questions in natural language:

• "How do we handle rate limiting in our APIs?"
• "Show me authentication implementations."
• "Find retry logic patterns.

Deep Search analyzes your code semantically, understanding context and meaning beyond literal text matches. This is especially valuable when:

• Different teams use different terminology for similar concepts
• You're searching across polyglot repositories
• You need to find conceptually similar code, not just matching strings

Want to learn more? Check out our introduction to Deep Search.

Where to next?

Look, if what you're doing – spending hours cloning repositories to read different function definitions – is working for you, then great! But I'm guessing you've also spent hours upgrading a library and solely relying on faith that nothing broke because you couldn't find all the dependencies. Those hours spent cloning and sifting add up. If there could be a world where you have all references and definitions at your fingertips, wouldn't that be a world you want to live in?

• No more context switching between your IDE, GitHub, and local clones
• No more guessing which services will break when you change a shared library
• No more manual audits to find every repository using a vulnerable dependency
• No more tribal knowledge about which version of a package each team uses

Cross-repository navigation combines text search with semantic code understanding. Search finds the code. Navigation shows you how it all connects. Whether you're debugging across microservices, managing shared libraries, or tracking down security vulnerabilities, you need both.

For your private code, enable SCIP indexing through auto-indexing or CI/CD setup.

Try these examples on public code at sourcegraph.com/search. Want to see how cross-repository navigation works for your organization? Contact us to learn more!