Sourcegraph Tour

Sourcegraph is a code search and intelligence tool for developers. It lets you search and explore your organization's code on the web, with integrations into your existing tools.

Let's tour Sourcegraph to see how it helps with everyday developer tasks.

Code review: Gain context on changed code

A developer reviewing a pull request or diff might need to understand the changed code to see whether it'll have any negative impacts or if other necessary changes were accidentally omitted.

Using Sourcegraph makes you a more effective code reviewer because code navigation makes it much easier to drill down into the implementation (to verify the correctness of the change) and enumerate call sites (to verify completeness of the change).

Requirements

Workflow

  1. Visit a pull request or code review in your web browser.
  2. Hover over source code in the diff (in added, unchanged, or deleted code) to see hover tooltips with documentation and Go to definition and Find references actions.
  3. Use these actions while reviewing the diff, such as to ensure that all call sites of a modified function are updated to account for any new assumptions or behavior.

To try this on an open-source pull request, install the browser extension and visit gorilla/websocket#342. Use Find references to see all cases in which the newly added AllowClientContextTakeover is used.

Example code: Learn how a particular function should be called

A developer adding a new feature needs to know how I should call a particular function.

Viewing cross-references (internal and external) on Sourcegraph is a great way to learn how to use a function or library because it shows you how it's actually being used, not just what the (possibly outdated or incomplete) documentation might suggest.

Requirements

Workflow

  1. Search on Sourcegraph for the name of the function you're trying to call. If you've installed any integrations, use those to initiate the search; otherwise, use the search box on the homepage of your organization's internal Sourcegraph instance.
  2. Find and click on a search result for the function you're looking for. (If needed, narrow your search using the suggested search filters below the search box or by adding your filters.)
  3. Click on the function's name in the code file (if it's not already highlighted).
  4. Click Find references to see how the function is called.
  5. Click through to various function call sites and use the after-line blame's authorship and recency information to gauge the quality of the call site as an example.

To try this on an open-source repository, start by searching for repo:dgrijalva/jwt-go parsewithclaims and follow the steps above to view internal and external references for the ParseWithClaims function.

Explore/read code: Understand what a function does and how it works

As a new developer on a project, I need to understand the implementation details of a certain part of the code.

Navigating your code with code navigation on Sourcegraph is a great way to understand code better because it works across all of your repositories (and all versions) without additional configuration, and it lets you share links with teammates if you need to ask specific questions about pieces of code.

Requirements

Workflow

  1. Search on Sourcegraph to locate the part of the code you're interested in. If you've installed any integrations, use those to initiate the search; otherwise, use the search box on the homepage of your organization's internal Sourcegraph instance.
  2. Find and click on a relevant search result or search suggestion. (If needed, narrow your search using the suggested search filters below the search box or by adding your filters.)
  3. Read through the code, click on a token, and then Go to definition to navigate to its definition as needed.
  4. If you have unanswered questions, use the blame information to determine who wrote the code, and send them a Sourcegraph link to the relevant code along with your specific questions.

Using an Open Source repo, you can follow the steps above to navigate to the implementation of the getLocation function. From there, keep drilling down depth-first until you get to the createScanner function. Explicitly, this involves reading getLocation until you reach the first new function, visit; then finding the implementation of visit via "get references" and reading visit until you reach the first new function, createScanner.

As a developer responsible for a service running in production, I need to respond to a crash report with a stack trace by quickly identifying and fixing the problem.

Diff search on Sourcegraph is a great starting point for your investigation into what broke, because it shows you all recent changes that match your query.

Requirements

Workflow

  1. Perform a diff search on Sourcegraph with the name of the function that the stack trace originates from, such as type:diff myCrashingFunctionName. If you've installed any integrations, use those to initiate the search; otherwise, use the search box on the homepage of your organization's internal Sourcegraph instance.
  2. Scroll through the search results, which show you all commits (and diffs) that match the function name, newest first. (If needed, narrow the diff search by adding search filters.)
  3. Find and click on a relevant search result. On the search results page, clicking on the commit message brings you to the diff (with code navigation), and clicking on the code in the commit diff brings you to the full file at the revision before or after the commit.
  4. Use Go to definition and Find references to understand the implementation changes and callers