Code search on Sourcegraph


Sourcegraph Server provides fast, advanced code search across multiple repositories. With Sourcegraph Server's code search, you can:

  • Use regular expressions and exact queries to perform full-text searches
  • Search any branch and commit, with no indexing required
  • Search commit diffs and commit messages to see how code has changed
  • Narrow your search by repository and file pattern
  • Define saved search scopes for easier searching
  • Curate saved queries for yourself or your org

This document is for code search users. To get Sourcegraph Server's code search for your organization, see the Sourcegraph Server product page.

Getting started

Start by visiting your company's Sourcegraph Server URL, or Sourcegraph.com to try it on open-source projects.

To begin, type a common term into the search box (such as test or open) and press the Search code button. You'll see full-text results from multiple repositories.

Next, try filtering the results by using the following operators in the search box:

  • repo:abc to show only results from repositories whose path contains abc (such as github.com/alice/abc)
  • file:xyz to show only matches inside files whose path contains xyz (such as src/xyz.js)

For example, your query might be: test repo:oauth2 file:internal/ (to find the string test in your github.com/alice/oauth2 repository's internal/ directory).

Concepts

Query

Tokens (all searches)

Your query can just consist of words, and you'll see results where those words appear in order in all files across all repositories. In addition to plain words, you can also use the following tokens in your query, separated by spaces:

Token Description Examples
regexp-pattern Plain words are actually interpreted as regular expressions (using the standard RE2 syntax ). Multiple words are joined with \s* to construct the combined pattern. (open|close)file
"any string" Surround a string in double quotes to find exact matches (including whitespace and punctuation). Use the \" and \\ escapes if needed. "system error 123"
repo:regexp-pattern
repo:[email protected]
Only include results from repositories whose path matches the regexp. A repository's path is a string such as github.com/myteam/abc or code.example.com/xyz that depends on your organization's repository host. If the regexp ends in @rev , that revision is searched instead of the default branch (usually master ). repo:alice/abc
repo:alice/[email protected]
-repo:regexp-pattern Exclude results from repositories whose path matches the regexp. repo:alice/ -repo:alice/old-repo
repogroup:group-name Only include results from the named group of repositories (defined by the server admin). Same as using a repo: token that matches all of the group's repositories. Use repo: unless you know that the group exists. repogroup:backend
file:regexp-pattern Only include results in files whose full path matches the regexp. file:\.js$
file:frontend/
-file:regexp-pattern Exclude results from files whose full path matches the regexp. file:\.js$ -file:test
-file:package.json
case:yes Perform a case sensitive query. Without this, everything is matched case insensitively. OPEN_FILE case:yes

Multiple or combined repo: and file: tokens are intersected. For example, repo:foo repo:bar limits your search to repositories whose path contains both foo and bar (such as github.com/alice/foobar). To include results from repositories whose path contains either foo or bar, use repo:foo|bar.

Tokens (diff and commit searches only):

All of the tokens above work for all types of searches. Below, find tokens only used for commit diff and commit message searches, which show changes over time:

Token Description Examples
type:diff
type:commit
Specifies the type of search. By default, searches are executed on all code at a given point in time (a branch or a commit). Specify the type: if you want to search over changes to code or commit messages instead (diffs or commits). type:diff
type:commit
author:name Only include results from diffs or commits authored by the user. author:alice
author:[email protected]
committer:name Only include results from diffs or commits commited by the user, which sometimes differs from the author committer:alice
committer:[email protected]
before:"string specifying time frame" Only include results from diffs or commits which have a commit date before the specified time frame before:"last thursday"
before:"june 25 2017"
after:"string specifying time frame" Only include results from diffs or commits which have a commit date after the specified time frame after:"3 weeks ago"
after:"june 25 2017"
message:"any string" Only include results from diffs or commits which have commit messages containing the string message:"fix"
message:"breaking change"

Diff search options

Add type:diff to your search query to search over commit diffs.

You can also search within commit diffs on multiple branches by specifying the branches in a repo: field after the @ sign. After the @, separate Git refs with :, specify Git ref globs by prefixing them with *, and exclude commits reachable from a ref by prefixing it with ^.

Commit message search options

Add type:commit to your search query to search over commit messages.

Separately, you can also use the message:"any string" token to filter type:diff searches for a given commit message.

Customizing search scopes

Every project and team has a different set of repositories they commonly work with and search over. Custom search scopes enable users and organizations to quickly filter their searches to predefined subsets of files and repositories. You can find samples such as "Test code", "Main repositories", and "Recent commits (unmerged)" on Sourcegraph.com, below the search box.

Custom search scopes can be specified at 3 different levels:

  • By site admins for all users: see the search scopes section in the server documentation
  • By org admins for all org members: in the org profile "Configuration settings" section, underneath the members list (see below)
  • By users for themselves only: in the user profile "Configuration settings" section (see below)

Org admins and users specify their custom search scopes in the search.scopes JSON field in their configuration settings in the profile page. For example, the following JSON would define two search scopes:

{
  "search.scopes": [
    {"name":"Test code","value":"file:(test|spec)"},
    {"name":"Non-vendor code","value":"-file:vendor/ -file:node_modules/"}
  ]
}

After editing and saving the configuration settings JSON in the profile page, the new search scopes take effect immediately. Instead of typing the set of files and repos you want to search over, you can now select your search scope from the buttons on the search homepage whenever you need.

Suggestions

As you type a query, the menu below will contain suggestions based on the query. Use the keyboard or mouse to select a suggestion to navigate directly to it. For example, if your query is repo:foo file:\.js$ hello, the suggestions will consist of the list of files that match your query.

You can also type in the partial name of a repository or filename to quickly jump to it. For example, typing in just foo would show you a list of repositories (first) and files with names containing foo.

Saved queries

Saved queries is a paid feature that lets you save and describe search queries so you can easily monitor the results on an ongoing basis. You can create a saved query for anything searchable, including diffs and commits across all branches of your repositories. Saved queries can be an early warning system for common problems in your code--and a way to monitor best practices, the progress of refactors, etc.

A saved query consists of a description and a query, both of which you can define and edit.

Saved queries are written as JSON entries in settings, and they can be associated with a user or an org:

  • User saved queries are only visible to (and editable by) the user that created them.
  • Org saved queries are visible to (and editable by) all members of the org.

To view saved queries, click on the Queries top navigation bar link.

To create a saved query:

  1. Click on the Queries top navigation bar link.
  2. Next to Saved queries, press the + New button.
  3. In the Description field, type in a human-readable description for your saved query.
  4. In the Query field, type in the components of the search query.
  5. In the user and org dropdown menu, select where you'd like the saved query to be saved.
  6. Click Create. The saved query is created, and you can see the number of results.

Alternatively, to create a saved query from a search you've already run:

  1. Execute a search from the homepage or navigation bar.
  2. Press the Save this search query button that appears on the right side of the screen above the first result.
  3. Follow the instructions from above to fill in the remaining fields.

Examples of useful saved queries

  • Recent security-related changes on all branches:

    • Query: type:diff repo:@*refs/heads/ after:"5 days ago" \b(auth[^o][^r]|security\b|cve|password|secure|unsafe|perms|permissions)
  • Admitted hacks and TODOs in code:

    • Query: -file:\.(json|md|txt)$ hack|todo|kludge
  • New usages of a specific function (change MYFUNC):

    • Query: type:diff after:"1 week ago" MYFUNC\(
  • Lint-disable on unmerged branches (customize for your own linters):

    • Query: repo:@*refs/heads/:^master type:diff after:"1 week ago" (tslint:disable)

Other tips

  • Hover over the search shortcut examples on the root page for more examples.
  • When viewing a file or directory, press the y key to expand the URL to its canonical form (with the full 40-character Git commit SHA).
  • To share a link to multi-line range in a file, click on the starting line number and shift-click on the ending line number (in the left-hand gutter).

Sourcegraph.com

Sourcegraph.com is a public instance of Sourcegraph Server that lets you search inside any open-source project on GitHub. For demo purposes, you'll be prompted to narrow your query if it would search across more than 30 repositories. To lift this limitation or to search your organization's internal code, Sourcegraph Server.

More information

For more product information, see the code search product page. To try it on open-source projects, visit the public instance at Sourcegraph.com.