
Sourcegraph is a universal code search tool, enabling you to search across both open source and your own private code repositories. Code search can help you onboard onto new codebases, contribute to open source, find bugs and error messages, understand dependency libraries, and more.

This cheat sheet style guide can help you get up to speed with Sourcegraph commands quickly. For more thorough tutorials on using Sourcegraph, refer to our [tutorials](https://learn.sourcegraph.com/tags/sourcegraph) and our [documentation](https://docs.sourcegraph.com/). 

You can use these commands on either [Sourcegraph Cloud](https://sourcegraph.com/search) or your own [Sourcegraph instance](https://docs.sourcegraph.com/admin/install).

## Searching an organization’s repository

By default, Sourcegraph lets you search globally, providing you with results from all the repositories you have access to. On Sourcegraph Cloud, this includes all currently indexed open source repositories. The `repo` command lets you dial down to the single repository level.

### Searching for or within a repository

The `repo` keyword lets you search a specific repository in your organization or on the web.

```
repo:[repository-path]
repo:[regular-pattern]
```

Searching with `repo:^github\.com/ORGANIZATION` will return all repositories in a given organization, where `ORGANIZATION` can be `sourcegraph`, for example.

<SourcegraphSearch query="repo:^github\.com/sourcegraph/.*" />


The `repo` keyword contextualizes the searches you perform on Sourcegraph. 

### Repository search: command chaining

When searching a repository, command chaining can be used to return more specific results depending on the expected results.

**Search for a repository that contains a file**

If you are searching for a file in a repository, use `repo.contains.file`.

```
repo:[repository-path] repo.contains.file([file-path])
```

For example, when searching for the `package.json` file in a project, this search query will return the file.


<SourcegraphSearch query="repo:^github\.com/sourcegraph/.* repo:contains.file(package.json)" />


A similar example that uses the content query to search for files is shown below.


<SourcegraphSearch query="repo:contains(file:package\.json$ content:ts)" />


This query returns repositories that contain a `package.json` file and has content written in TypeScript.


**Search for a repository that contains some content**

Suppose you are searching for some content in a repository, such as a library. Use `repo.contains.content`.

```
repo:[repo-path] repo.contains.content([content])
repo:[repo-path] repo.contains.content([regular-pattern])
```

We can search for the `mdi-react` library in Sourcegraph, for example:

<SourcegraphSearch query="repo:^github\.com/sourcegraph/.* repo:contains.content(mdi-react)" />


The above query returns repos that have `mdi-react` among its contents.

## Language-specific search

Use `lang` when searching code to narrow the scope of your search to one programming language. 

```
lang:[programming language]
```

We can search for results within the C++ or Python programming languages.


<SourcegraphSearch query="lang:c++" />

<SourcegraphSearch query="lang:python" />


By default, searches are case insensitive.

Prepending a hyphen can exclude results from a particular programming language.

```
-lang:[programming-language]
```

To exclude Java, you can perform the following search.

<SourcegraphSearch query="​​-lang:java" />

Narrowing your search scope down to specific languages can ensure that you find the code that is most relevant to your needs.

## Searching based on time periods

If you are searching for code committed before or after a time period, you will use `before` and `after`

```
before:[time-period]
after:[time-period]
```

Sometimes the time period can be literal, like `last week`, `last year`, `3 months ago`, `february 10 2021` or have actual dates in the format `dd/mm/yyyy`.

```
before:last week
after:february 10 2021
before:02/01/2019
```

To search between dates, keywords like `and` can be combined with `before` or `after` to return dates within a given period.

<SourcegraphSearch query='repo:sourcegraph type:commit after:"july 9 2021" and before:"july 10 2021"' />

Time-based search is usually used along with other search commands to further narrow down search results.

Note that `before` and `after` only work in conjunction when combined with `type:diff` or `type:commit` commands.

## Search in archived repositories

The `archived` keyword will bring up those results from repositories that have been archived.

```
archived:[yes/only]
archived:yes
archived:only
```

We can surface only archived repositories within the Sourcegraph organization with the following query.

<SourcegraphSearch query="repo:sourcegraph archived:only" />

This can help us understand past decisions made within a given codebase. 

## Case sensitive search

Use `yes` or `no` with the `case` search query to specify if the search should be case sensitive or not. By default, searches are case insensitive.

```
case:[yes/no]
case:yes
case:no
```

Suppose you would like to check to align the style of a given codebase to help you bring all function calls in Python to be consistent with the [PEP 8](https://www.python.org/dev/peps/pep-0008/) guidance. You can use Sourcegraph to understand which functions are using camelCase rather than lowercase names with underscores between words (also called snake_case).

<SourcegraphSearch query="case:yes lang:python myFunction" />


If you would like to find all declared functions that use camelCase, you can try combining this query with regular expressions.

## Searching by types

Types define the scope of code search. A search scope consists of commits, diffs, symbols, repos, paths and files. It is typically used alongside other search commands to further narrow search results.

```
type:[commit|paths|diff|symbol|repo|files]
```

Here is an example to show us time-based commits on the Sourcegraph repo.

<SourcegraphSearch query="repo:sourcegraph after:yesterday type:commit" />

A `type` scope can use the following commands, which will restrict search to the following:
* `commit` — commits to a repository
* `diff` — show [diffs](https://git-scm.com/docs/git-diff), or changes, within a repository
*`repo` — repositories available to you
* `files` — returns files 
*`symbol` — returns files that contain names or keywords in a library.

Searching by type can help you find exactly what you need in a codebase by narrowing down the scope of your search. 

## Searching commit messages matching a string

If a commit message is known, it can be helpful to use the `message` keyword to bring up relevant commits.

```
message:[commit-message]
message:[string-regex-pattern]
```

We can find all commit messages with “fix” in the `sourcegraph/sourcegraph` repository by searching the following.

<SourcegraphSearch query="repo:^github\.com/sourcegraph/sourcegraph$ type:commit message:fix" />

Note that the message keyword only works for `type:diff` or `type:commit` queries.

## Searching code by commits and diffs 

The `author` keyword returns code search results that were created by a user. This keyword only works for `type:diff` or `type:commit` queries.


```
author:[author-name]
```

Adding a hyphen in front of the `author` keyword omits code content created by a given author.

```
-author:[author-name]
```

Search for all code diffs by the Renovate app within our Sourcegraph repository.

<SourcegraphSearch query="repo:^github\.com/sourcegraph/sourcegraph$ author:renovate type:diff" />

You can also search by `committer:git-email` with the same `type` constraints.

## Return a certain number of results

Sourcegraph returns pages filled with search results. To stop searching after a given number of results are returned, use the `count` command.

```
count:[number|all]
```

For example, `count:5` would return the first 5 results of a given query.

<SourcegraphSearch query="repo:sourcegraph/learn type:commit count:5" />

The `all` option returns all results from a search.

The `count` keyword may also be used to return _more_ results, not just  _fewer_ results. This can enable you to display more than the default 500 results that are returned.

## Searching for or within forks

The `fork` keyword restricts the scope of search results to either include, exclude, or return only  forks of a given repository.

```
fork:[yes|no|only]
```

The `yes` option includes forked repositories, the `no` option omits the results from forks, and the `only` option searches only forked repositories.

One use case for searching forked repositories is looking for how users personalize open source libraries.

## Timing out searches

To set the duration before a search times out, you’ll use the `timeout` keyword. Time units that can be used include nanoseconds (`ns`), microseconds (`us` or `µs`) , milliseconds (`ms`), seconds (`s`) or minutes (`m`).

```
timeout:[time-duration-with-unit]
```

This is useful when searching many repositories at the same time to give search more time to return useful results. By default, timeout is 10 seconds, however, when using the `timeout` command, timeouts can be set to over a minute. When this scope is provided, search is given more time to complete.

<SourcegraphSearch query="timeout:40s" />

Alternatively, if you are receiving too many results, you can decrease the time of search.

## Search by repository visibility

Restricting search by codebase visibility is done with the `visibility` command. You can restrict search to public or private repositories.

This is useful if you want the results of a search to be explicitly narrowed down to repositories that are private and accessible to you or repositories that are public. 

Except when explicitly set, all searches return results from both public and private repositories accessible to you.

```
 visibility:[any|private|public]
```

When logged into Sourcegraph, you can change your context to your username and then run the following command to show all of your available private repositories.

<SourcegraphSearch query="visibility:private" />

This can allow you to search across the code that is private to only you. _Please note that searching private code on Sourcegraph Cloud is currently in Public Beta._

## Further resources

To learn more about how to search effectively with Sourcegraph, you can read through our Sourcegraph search series:
* [How To Search with Sourcegraph using Literal Patterns](/how-to-search-code-with-sourcegraph-using-literal-patterns)
* [How To Search with Sourcegraph using Regular Expression Patterns](/how-to-search-with-sourcegraph-using-regular-expression-patterns)
* [How To Search with Sourcegraph using Structural Patterns](/how-to-search-with-sourcegraph-using-structural-patterns)

You can also check out [Sourcegraph product documentation](https://docs.sourcegraph.com/) and [Sourcegraph tutorials](https://learn.sourcegraph.com/tags/sourcegraph).


Getting started with Sourcegraph universal code search

A guide to help you get up to speed with Sourcegraph's commands quickly

How to search code with Sourcegraph — a cheat sheet


Sourcegraph code search is a search engine that allows you to search code in your own repositories as well as across public open source code. It supports three kinds of search patterns: literal patterns, regular expression patterns, and structural patterns. In this article, we’ll explore literal search patterns and how to use them.

Performing a literal search is useful when you know the exact string that you’re looking for in a code base, like a particular function or variable name. You can find all occurrences of the name across multiple repositories by using your query as a literal pattern. It’s also useful for finding textual content — like error messages or comments — in the code.

By default, all search queries on Sourcegraph are treated as literal patterns. We’ll discuss a few use cases to find useful results with Sourcegraph.

## Finding function calls and definitions

As a developer, there are many times you may need to learn a new codebase: you may need to understand how best to use a new package, may need to be onboarded into an existing project, or may want to learn best practices from tried and tested software. A productive way to become familiar with a codebase is through selecting a function and understanding how it’s used throughout the code and in what contexts.

For example, if you’re learning how the Linux kernel works, one of the topics that you may want to understand is how Linux uses linked lists. Because linked lists are used throughout the Linux kernel and in driver code, they are a foundational starting point to familiarize yourself with the codebase.

The linked list data structure in Linux is called `list_head`. We can find all instances of the `list_head` structure by searching for it directly:

<SourcegraphSearch query="list_head"/>

As you review the results, you may notice that there are some common functions that are frequently used together with linked lists. One of these functions is `list_add_tail`. To explore further and find all instances of `list_add_tail`, we can start a new search for that specific function:

<SourcegraphSearch query="list_add_tail"/>

Literal search patterns can be used to find more than just functions or variables. They can also be used to find longer pieces of text, like error messages, as we’ll explore in the next section.

## Finding error messages

Literal search can help you find where a particular piece of text occurs within code. For example, if you’re seeing an error message while debugging, it can be helpful to find where that message is defined in the code to get a better idea of what is causing it. You can search for an exact match by copying the error into your search.

Let’s try an example. React is a framework used by many web apps, and its error messages are sometimes hard to debug. When a React component throws an error, it produces an error message like, `React caught an error thrown by Component`. When you get an error message like that, it isn’t always clear what is going on. To learn more about the source of the error, you can search for the error message itself:

<SourcegraphSearch query="React caught an error thrown"/>

By finding where an error message is defined, you can start to understand what conditions will cause this error. In this case, it happens when React catches an error that happened during the rendering phase in one of your components.

This kind of search also gives you an understanding of the inner workings of the codebase, and that can be really helpful to get a better mental model of how it works.

## Finding sequences of words

By default, when searching for literal patterns in Sourcegraph, the entire query will be searched, even if the pattern consists of multiple worlds. You should not put your query in quotes: we’ll go into more detail about this now.

Unlike a web search engine, if you search for two or more words on Sourcegraph, like `const counter`, then you’ll only get results for `const` immediately followed by `counter`, as in the example below.

<SourcegraphSearch query="const counter"/>

Returning to our example in the Linux kernel, we can narrow down our search for `list_head` to only the cases where it’s used as a simple structure ([`struct`][struct]), by searching specifically for the `struct list_head` pattern:

<SourcegraphSearch query="struct list_head"/>

If you want to find all instances of those two words appearing in the same file but not necessarily in sequence, then you can use the `and` operator, or you can switch to regular expression mode.

To use the `and` operator, add it to your search. The following query will find occurrences of `list_head` and `list_add_tail` when they are present anywhere in the same file.

<SourcegraphSearch query="list_head and list_add_tail"/>

If you try one of these examples with quotes around the search query, like `"const counter"`, you’ll notice that you get no results. This is because the quote characters are interpreted literally, so Sourcegraph will search for textual data that includes those quote characters.

There are cases where searching for quote characters is useful. We’ll explore that in the next section.

## Finding quoted string constants

Because quote characters are treated like any other character when you’re in literal pattern mode, you can search for quoted strings by including the quotes in your search.

For example, the quoted string `"ENOENT"` represents the error when a file is not found in Linux, and it’s found in many codebases:

<SourcegraphSearch query='"ENOENT"'/>

By including the quotes in the search query, you can compare this search with the same string, but without quotes. You’ll receive other results, where the string isn’t necessarily in quotes.

<SourcegraphSearch query='ENOENT'/>

## Learn more

We’ve explored how to use Sourcegraph to search for literal patterns like function names, variables names, error messages, and strings. You can learn more about Sourcegraph search syntax in the [documentation].

Literal search patterns are a useful starting point, but often you need to search for patterns in your code that require more flexibility. Sourcegraph offers two other types of patterns: [regular expressions] and [structural search].

To go beyond literal patterns, you can use regular expressions or structural search patterns.

**Related links:**

- [Sourcegraph search query documentation][documentation]
- [Sourcegraph regular expression search][documentation]
- [Sourcegraph structural search][structural search]

[struct]: https://en.wikipedia.org/wiki/Struct_(C_programming_language)
[documentation]: https://docs.sourcegraph.com/code_search/reference/queries
[regular expressions]: https://docs.sourcegraph.com/code_search/reference/queries#regular-expression-search
[structural search]: /how-to-search-with-sourcegraph-using-structural-patterns


Searching code with Sourcegraph using literal search

Learn how to use literal search patterns to search code on Sourcegraph.

How to search code with Sourcegraph using literal patterns


Sourcegraph lets you search code across repositories, supporting three kinds of search patterns: literal patterns, regular expression patterns, and structural patterns. In this article, we’ll take a look at regular expressions patterns and how to use them in Sourcegraph.

Regular expressions, often shortened as _regex_, help you find code that matches a pattern (including classes of characters like letters, numbers and whitespace), and can restrict the results to anchors like the start of a line, the end of a line, or word boundary.

## Enabling regular expression search on Sourcegraph

Start searching with regular expression patterns by toggling the dot asterisk (`.*`) button towards the right-hand side of the search box. When you mouse over it you’ll receive a tooltip that reads `Enable regular expression`.

<GifLikeVideo url="https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/enable-regex.mp4"/>

Once it is highlighted, you're ready to search with regular expressions.

## Finding a pattern

Regular expressions are useful when you're looking for any strings that match a particular pattern. A common pattern in CSS is the RGB hex color code, like #6495ED (cornflower blue) or #663399 (Rebecca purple).

To match RGB hex color codes, we can write a regular expression that has three parts:

- A hash symbol (`#`)
- A character class for hexadecimal characters: `[0-9a-f]`
- A repetition operator, indicating that we're looking for 6 characters that match the above character class: `{6}`

Combining these parts into one regular expression, we can use this pattern in a Sourcegraph search. To make the results more relevant, we can add the `lang:css` filter so that we target only CSS files.

<SourcegraphSearch query="#[0-9a-f]{6} lang:css" patternType="regexp"/>

Regular expressions are useful for finding patterns like this, where certain classes of characters are repeated a certain number of times.

## Finding a set of function calls

One use case for regular expression search is when you are trying to find examples of file system function calls. You may be interested in functions that read or write files: `readFile` and `writeFile`. While you could search for them individually, it can be useful to perform one search that includes results for both functions.

`readFile` and `writeFile` have a pattern in common: they both end in `File`. We can write a regular expression that expresses this pattern like so:

<SourcegraphSearch query="(read|write)File" patternType="regexp"/>

The above search query uses the regular expression syntax of a pipe (`|`) character, which signifies “or”. We can read the query as a search for “`read` or `write`” followed by `File`.

If you would like to narrow down the scope of the search, you can modify this pattern further. If you would like to specify that you would like to use the file system prefix of `fs`, as in `fs.readFile` or `fs.writeFile`, you can add that prefix to the search. Because the `.` dot character notation has a special regex meaning (it will match all characters), we will want to escape the dot with a backslash (`\`).

<SourcegraphSearch query="fs\.(read|write)File" patternType="regexp"/>

Regular expressions are also useful if you’re looking for a variable that can contain a mix of alphabetic and numeric characters, like `id1`, `id2`, `id3` and so forth. To narrow down the results, we can add the `type:symbol` filter.

<SourcegraphSearch query="id\d+ type:symbol" patternType="regexp"/>

In this case `\d+` matches one or more digits.

## Using spaces in regular expression patterns

It’s common to be looking for a pattern with two keywords, separated by any other text in between.

When using regular expressions in Sourcegraph, the space character matches any characters between keywords. So if you search for two words in regular expressions mode, like `auth service`, you’ll get results where `auth` and `service` are found on the same line, and any other number of characters (not limited to spaces) may be in between.

<SourcegraphSearch query="auth service" patternType="regexp"/>

When you use spaces in regular expressions in Sourcegraph, the space character is automatically interpreted as replaced by the `.*` pattern. This pattern matches any number of characters on the same line (including none). When you’re looking for two words appearing together in a code base, but not necessarily right next to each other, regular expression mode is a useful way to find relevant results.

## Finding whole words using word boundaries

By default, Sourcegraph finds all occurrences of your search pattern even when it occurs inside of a longer word. Sometimes when you’re searching for a pattern like `count`, you’re only interested in functions or variables called `count` and not `counter` or `countId` or `countItems`. In those cases, you should specify that you’re looking for an exact keyword. You can do this with the regular expression `\b`, which stands for _word boundary_.

<SourcegraphSearch query="\bcount\b" patternType="regexp"/>

We can use this to improve the search from our earlier example. You may have noticed that the search for `readFile` and `writeFile` returned other functions that started with those patterns, like `readFileAsync`. By using a word boundary, we can restrict the search to only match the exact function name.

<SourcegraphSearch query="(read|write)File\b" patternType="regexp"/>

In the above search we’re adding `\b` at the end of the query, but not at the beginning. This way, we can express that we’re looking for matches that end with this pattern, but may have an alternate prefix.

## Finding patterns at the start of a line

We’ve looked at ways to find matches that are located anywhere in a given line of code. What if you want to narrow down your search to find only the instances when the word is located at the start of the line?

You can use the line start character, `^`, and the line end character, `$`, to anchor your search. For example, here is a search that matches the word `let` when it occurs at the start of the line.

<SourcegraphSearch query="^let" patternType="regexp"/>

This won’t match lines where there’s anything before `let` on the line. That means if there’s whitespace at the beginning of the line, like tabs or spaces for indentation, then that line won’t be considered matches. Since indentation is common in code, you may want to modify the search to include results where `let` can be optionally preceded by any amount of whitespace.

This is where the `\s*` pattern is useful; it matches any number of whitespace characters (zero or more). By adding it in front of `let`, you can now include all results where the line has indentation whitespace.

<SourcegraphSearch query="^\s*let" patternType="regexp"/>

## Learn more

Regular expressions are a powerful syntax for searching code, and in this tutorial we’ve only covered some fundamental features. Sourcegraph uses the RE2 style of regular expressions, which you can learn more about by reading the [RE2 documentation](https://github.com/google/re2/wiki/Syntax).

When you’re looking for nested structures in your code, like matching brackets, argument lists, or if-then statements, then structural search can be helpful. Learn about structural search in "[How to search with Sourcegraph using structural patterns](how-to-search-with-sourcegraph-using-structural-patterns)."


Using RegEx with Sourcegraph

Learn how to use regular expression search patterns to search code on Sourcegraph.

How to search code with Sourcegraph using regular expression patterns


Structural search helps you search code for syntactical code patterns like function calls, arguments, `if`...`else` statements, and `try`...`catch` statements. It's useful for finding nested and recursive patterns as well as multi-line blocks of code.

Structural search patterns are one of the three search patterns supported by Sourcegraph, along with literal patterns and regular expressions. They're different from regular expressions because they take into account the syntax of code, like balanced brackets, quoted strings, and delimiters.

## Enabling structural search on Sourcegraph

Enable structural search by clicking the icon of two square brackets (`[]`) to the right of the search box:

<GifLikeVideo url="https://storage.googleapis.com/sourcegraph-assets/learn/tutorial-images/enable-structural-search.mp4"/>

Once structural search is enabled, the icon will be highlighted and you can begin performing structural searches.

## Finding function calls

Suppose we're debugging a program's error output and trying to figure out where that output is coming from in the code. We want to find calls to the `fprintf` function that writes to the standard error stream (`stderr`), which look like this:

<PrismSyntaxHighlighter
input='fprintf(stderr, "%s", message)'
language='c'
/>

If we're looking only for error output, we want to match all other instances where `stderr` is the first argument of the call.

This is a situation where structural search can help:

<SourcegraphSearch query="fprintf(stderr, ...) lang:c repo:^github\.com/torvalds/linux$ " patternType="structural" />

In this example, we're using a placeholder, `...`, for the remaining arguments. This ellipses placeholder is called a "hole" in the pattern. Structural search syntax uses "holes" as placeholders for syntactic structures. In this case, the placeholder will match the remaining function arguments.

## Matching multiple function arguments

The above example gave us results that use `stderr`, but we may want to narrow down our search further. For example, we may want to match only `fprintf` calls where the final argument is `err`. We can add `err` to our search query to match it in the position of the last argument:

<SourcegraphSearch query="fprintf(stderr, ..., err) lang:c repo:^github\.com/torvalds/linux$ " patternType="structural" />

The above query matches `fprintf` calls where the first argument is `stderr` and the last argument is `err`. The `...` hole will match any number of arguments in between, and that's particularly useful for a function like `fprintf`, which accepts a variable number of arguments.

## Using multiple holes

You can use more than one `...` hole in a search. If we want to find an exact match for the second argument to `fprintf`, but accept any other arguments, we could use a hole in both the first and last argument position:

<SourcegraphSearch query='fprintf(..., "%s", ...) lang:c repo:^github\.com/torvalds/linux$' patternType="structural" />

The second argument to `fprintf` is expected to be a format string. In this above example, we'll find matches where the second argument matches the string `"%s"` exactly.

## Matching holes within strings

Structural search can interpret quote-delimited strings, too. Using the `...` hole within a string, we can match partial string literals in the code. For example, we can expand our previous search to match any format strings that start with `ERROR:`

<SourcegraphSearch query='fprintf(..., "ERROR: ...", ...) lang:c repo:^github\.com/torvalds/linux$' patternType="structural" />

In the above example, we're using three `...` holes:

- The first one accepts initial arguments
- The second one, within the string, accepts any string content that comes after the "Error:" portion of the string
- The third one accepts any final arguments.

As a whole, this search pattern helps us find `fprintf` calls that match this particular `"Error: ..."` pattern that we're looking for.

## Matching part of an expression

The `...` placeholder can also match partial content between brackets, like part of an expression.

Suppose we're investigating a bug that only happens when an array, `parts`, is empty. In the following example, we're looking for `if` statements where the condition starts with a check for whether the array is empty:

<SourcegraphSearch query="if (!parts.length && ...) { ... } lang:javascript repo:^github\.com/google/.* count:all" patternType="structural" />

The above example will match `if` statements with any additional sub-expressions that follow the `&&` operator.

In the results, we'll find code blocks that get executed when that particular array is empty, which might bring us closer to finding the cause of the bug that we're investigating.

## Finding blocks of code in brackets

Balanced bracket matching works with round brackets or parentheses, `()`, square brackets, `[]`, and curly brackets or braces `{}`.

By using curly brackets in a structural search pattern, you can match entire code blocks.

Suppose that you're working on improving a Java codebase, and you want to clean up the code's `try`...`catch`...`finally` statements. In Java, an empty `catch` clause is allowed, but it often represents an opportunity to omit the clause entirely or to refactor it.

We can construct a structural search pattern to find empty `catch` clauses that can be improved. In this case, we'll use the hole placeholder inside of curly brackets to match code blocks, but we'll deliberately keep the `catch` clause empty in order to find only the empty blocks there.

<SourcegraphSearch query="try {...} catch (...) { } finally {...} lang:java repo:^github\.com/elastic/elasticsearch$" patternType="structural" />

You can use curly brackets in structural search to match other types of code blocks as well, like `for` loops, `switch` statements, and object definitions.

## Learn more about structural search

We've discussed a few examples of structural search patterns in this article, but there are more features available in the syntax that we haven't covered. To learn more, visit the [Structural search reference](https://docs.sourcegraph.com/code_search/reference/structural) in the Sourcegraph documentation.

If you're curious about where Sourcegraph's structural search syntax originates, and want to learn more about the concept of structural search in general, you can learn more by visiting the [Comby website](https://comby.dev/), a tool that can both search and modify code. Sourcegraph's structural search syntax is a variant of the syntax supported by Comby.

## Other ways to search with Sourcegraph

While structural search is helpful for certain types of searches, there are cases where it's more straightforward to express what you're looking for as a regular expression. Learn more about searching with regular expressions in [How to search with Sourcegraph with regular expression patterns](/how-to-search-with-sourcegraph-using-regular-expression-patterns).

If you're not looking for a pattern but an exact match, then a literal search may be more straightforward. Learn about literal search patterns in [How to Search with Sourcegraph with literal patterns](/how-to-search-code-with-sourcegraph-using-literal-patterns).


Structural code search with Sourcegraph

Learn how to use structural search patterns to search code on Sourcegraph.

How to search code with Sourcegraph using structural patterns


<EmbeddedYoutubeVideo id="r2CpLe1h89I" />

## Related links

- [Sourcegraph Cloud code search](https://sourcegraph.com/search)
- [Sourcegraph docs](https://docs.sourcegraph.com)
- [Read about literal search patterns](/how-to-search-code-with-sourcegraph-using-literal-patterns)
- [Watch: Three Ways to Search with Sourcegraph (Video)](/three-ways-to-search-code-with-sourcegraph)

## Transcript

Have you ever been faced with an error message and spent a really long time trying to figure out where it was coming from?

My name is Marek. I'm an engineer at Sourcegraph. And I'm going to share with you my own error message story.

A few months ago, I was working on a browser extension in Chrome. And I started seeing this unfamiliar message that I hadn't seen before. It looked something like this. "Extension context invalidated." What does that even mean? I didn't know where this error was being thrown. And I didn't know where to start looking. We were loading code from a few different repositories into this browser extension bundle. So I wasn't sure where this was coming from.

At first, I tried doing some searches right in my editor to try to find an exact match for the text of this error message. But I got nowhere. I didn't find any matches in the repository that I had open at all.

So I'll show you how I actually used Sourcegraph to do a code search that helped me find the answer. By default, Sourcegraph searches for code in literal search mode. That means it looks for an exact match. For an error message, this is pretty convenient. And I can show you by pasting that error message directly into the search box. Now, I don't need to surround this search with quotes, because literal search will by default already search for the entire thing.

As soon as I get results, there's a hint about where this is coming from. And that's in the name of this repository that I'm getting. So I'm seeing chromium as the repository. This gives me a hint that this is part of the Chrome browser itself and actually not at all a part of the code base that I was working on. The chromium source code is in a public GitHub repository, and Sourcegraph searches over public code. This helped me save a lot of time and a lot of struggle to get to the bottom of this error message. And it turns out it was an issue with the way that the browser extension was being reloaded for development.

Sourcegraph's default search mode is great for error messages like this, but if you're looking for patterns, you can also use regular expressions. And you can also use structural search. So you can take a look at our documentation to learn more about that.


Finding software error messages with Sourcegraph universal code search

Learn about finding error messages in your code with Sourcegraph.

How to find error messages with Sourcegraph (video)


<EmbeddedYoutubeVideo id="w-RrDz9hyGI" />

## Transcript

Sourcegraph code search lets you search over public repositories or your own private code. It helps you answer questions that start with _where_. For example, where is this function used across all of our repositories? Where are we using these dependencies? Or, where are all the matches for this particular regular expression search?

But, what if you could search over space and time? Sourcegraph commit search helps you answer questions that start with _when_. When was a particular keyword mentioned in a commit message? When did we add or remove a specific string across our repositories? When did a commit or a diff contain an exact function name? 

My name is Marek. I'm an engineer at Sourcegraph. And I want to show you how to search over commits and diffs with Sourcegraph.

Suppose I'm looking for some particular commits that made some changes to our database logic. In this case, I will look for commits that have the keyword `database` in the commit message. To do this, I'll use the `type` filter to specify that I'm looking for commits, and I'll use the `message` filter to specify the keyword that I want to find, in this case, the keyword `database`. I'll also add a repository filter to narrow down the results.

In the results, I see a list of commits being returned. I can browse the commit messages and also see how long ago they were committed. If I click on a commit, I can also see the entire diff associated with it, so I can browse through the changes.

Now, it can be useful to narrow down my search if, for example, I know that the commits that I'm looking for occurred in a particular time range. I can add a `before` filter and provide a date and combine it with an `after` filter to specify a range of time. Now in some cases, I might be looking for commits from a particular author on my team. I can use the `author` filter and provide a name to narrow it down further.

I've shown you an example of searching over commit messages. But I can also search over the actual diff contents of every commit as well. This is helpful if I'm really looking for an exact string that was either added or removed in a particular change. To perform a diff search, I'll start with the `type:diff` filter. Now I can specify any search query that is supported by Sourcegraph. In this case, I could use a regular expression to find all matches that start with `user_`. And like before, I'll use a repository filter to narrow down the results.

In the results, I see matches in the diffs of commits that were made in this repository across time. Now, I'm seeing matches both in lines added and lines removed. Now I can improve my search. If I'm only looking for instances where this particular match was added, not removed in a commit, I can do that by adding a `select` filter, and providing `commits.diff.added` as the value. Now, I'm only getting results where this particular match was in the added content of a commit.

Other types of filters that are supported by regular Sourcegraph code search are supported in commit search as well, such as the language filter, or the file filter to help you narrow down by file path. With commit and diff search. Sourcegraph helps you find everything that you're looking for in your code, answering not just _where_ it is, but _when_ it happened. To learn more about the different ways that you can search with Sourcegraph check out the links below.

## Learn more

Browse our [learning resources about Sourcegraph search](/tags/search).


Learn about using Sourcegraph to search commits and diffs.

How to search Git commits and diffs with Sourcegraph


<EmbeddedYoutubeVideo id="GnubTdnilbc" />

## Transcript

Structural search is one of the three ways that you can search code with Sourcegraph. 

My name is Marek. I'm an engineer at Sourcegraph, and in this video, I want to show you how you can use structural search in Sourcegraph. And I'll share examples of the kinds of things that you can do with it.

Structural search is a way to search code that takes into account the code’s syntactic structure. This means it goes beyond regular expressions, which are great for matching patterns of characters, and it lets you match patterns in the structure and the syntax of the code.

Let's jump into some examples. We can use a well-known codebase, the Linux kernel. It's mostly written in C, but you can use structural search with any programming language. You can search over any public repositories that are indexed by Sourcegraph. And you can also use Sourcegraph to search your own private code.

To enable structural search, click on the structural search toggle on the right side of the search box. It's represented by an icon of square brackets (`[]`). I'll begin to search with a `repo` filter to select the Linux kernel repository on GitHub that I want to use for these examples. I'll use the language filter to specify that I'm looking for files written in C. Because structural search takes into account the programming language in its matches, you'll get better results if you specify the language with the language filter.

Suppose I want to find all calls to a function with a particular first argument. Let's say I'm looking for the function `fprintf` and I want to find all cases where the first argument is the standard error stream, or `stderr`. Since I'm only interested in the first argument, I can use a placeholder for the remaining arguments. Placeholders in structural search are called holes in the pattern. The ellipses is a type of hole that matches any number of arguments. In the results, I get matches for the pattern of the function call I was looking for, followed by any various other arguments in the function call.

Now, suppose I want to do another search for instances of the `fprintf` function. But this time, I'm interested in matching a string argument. Structural search supports using placeholders or holes in the pattern inside of quoted strings. Here's a search where I use the ellipses hole to match any initial arguments, followed by a string that starts with `ERROR` and an ellipses within the string to match anything in the string after that, and finally, followed by another ellipses to match any remaining arguments. The results show instances of these function calls, where there is a string argument that matches this pattern.

Now, let me show you how to take this example further and demonstrate that structural search understands nested structures, too. Suppose I want to narrow my search to find instances where the last argument is a specific expression. Let's say it's a call to a function named `strerror`. I can use the ellipses hole in the brackets to find all calls that match this regardless of what the arguments actually are.

I can also flip this pattern around. Suppose that I know the name of the arguments that I want to find in this function call, but I want to match any function name. I can use the ellipses hole instead of the function name, but then specify the exact argument name that I'm looking for. For example, `errno`. Now I'll get results where this specific argument name matches, but the name of the function being called here can match anything.

Now I want to show you an example of a more advanced format for the holes in a pattern. In a structural search, the ellipses placeholder matches all patterns. But sometimes we want to narrow that down further, for example, to find identifiers that conform to a particular regular expression. I'll update this pattern with a hole in the final argument that will narrow down the matches by regular expression. This is part of the structural search syntax that lets you be more detailed in the matches that you're looking for. The colon and the square brackets indicate that this is a structural search hole pattern. The tilde (`~`) indicates the start of a regular expression. And then we have a regular expression that matches any identifier that starts with `opt_`. And in the results now we're getting matches where this final argument conforms to the regular expression in this pattern that we've provided.

I hope this gives you an idea of the kinds of things that you can do with Sourcegraph. Structural search is one of the three search modes supported by Sourcegraph, the others being literal search and regular expression search. To learn more about how you can use Sourcegraph to better search and better understand your code. Check out our documentation and our learning resources add the links below.

## Learn more

- Watch: [Three ways to search with Sourcegraph](/three-ways-to-search-code-with-sourcegraph)
- Read: [How to search code with Sourcegraph — a cheat sheet](/how-to-search-code-with-sourcegraph-a-cheat-sheet)
- Browse all [Sourcegraph search tutorials](/tags/search)
- [Sourcegraph search documentation](https://docs.sourcegraph.com/search)

Learn about Sourcegraph structural search patterns.

How to use structural search in Sourcegraph


<EmbeddedYoutubeVideo id="XLfE2YuRwvw" />

## In this video

- Literal search ([tutorial](/how-to-search-code-with-sourcegraph-using-literal-patterns), [docs](https://docs.sourcegraph.com/code_search/reference/queries#literal-search-default))
- Regular expression search ([tutorial](/how-to-search-with-sourcegraph-using-regular-expression-patterns), ([docs](https://docs.sourcegraph.com/code_search/reference/queries#regular-expression-search))
- Structural search ([tutorial](how-to-search-with-sourcegraph-using-structural-patterns), [docs](https://docs.sourcegraph.com/code_search/reference/structural))

## Transcript

Hi, my name is Marek. And I'm going to tell you about the different ways that you can search with Sourcegraph. So, Sourcegraph supports three different search modes: literal search, regular expressions, and structural search. I'll tell you a little bit about each one and how you can use them.

By default Sourcegraph searches in literal search mode. This is useful when you're looking to find an exact match. For example, if you're looking for a function name, or a variable name, or an exact string in your code. Let's say that I'm looking for a function called "ReadFile". I can search for directly, and it'll find exact matches. But I can also narrow this down by saying I'm only looking for results in the Go language. So I'm getting results from a variety of different repositories that match the exact query "ReadFile".

Sometimes you're not looking for an exact match, but you're looking for a pattern. Regular Expression search can help you find patterns in you in your code. Suppose I'm looking for CSS colors that are defined as six character hex codes. I know that the CSS color code format can be defined as a regular expression. And it starts with a hash symbol, followed by characters in the range between zero and nine and between A and F. And that's repeated six times. So I've just written that pattern as a regular expression. And I can also add the keyword that narrows this down to only CSS files. And I'll enable regular expression mode for this one. So now I'm getting results that are matching anything that looks like a hex color code. I could expand on this query by adding that I'm only looking for cases where background color is the property that's been set. So now with this search query, I will see only results that match background color, followed by a hex code.

Regular expressions are useful when you're looking for a pattern in your code. But sometimes you want to take into account the actual structure of your code. This is where structural search can help. Let me show you an example. I'll enable structural search. And let's say for example, I'm looking for a function call to a function called "WriteFile". And I know that the instance that I'm looking for is where the first argument is called "path". But I wanted that to match any other arguments after that. So I'm going to use the three dots that match any other arguments in a structural search. I'm also going to restrict this only to Go files. So now I'm getting matches that correspond to function calls where the first argument is path. But the other arguments could be anything. Notice that this is using matching brackets. So even if there are expressions in this function call that contain other brackets, the search will still take that into account and correctly match the entire function call.

Now, in some cases, I see that the constant that's used as the last argument here is relevant. So I may want to narrow the search down and actually search for only the calls where a particular constant is being used as the final argument here. So if I redo this search, the now I'm seeing that I'm getting results for this function call where the first argument is the one I've specified, as well as the last one, but I'm matching any arguments in between, and they can be any expressions in the code.

So I've given you an overview of the three different ways that you can search with Sourcegraph. With each of these modes, you can also filter down by a variety of criteria like programming language, repositories, and file names and a lot of other things too. So you can look at our search query docs to learn more.


Searching code with Sourcegraph using literal patterns, regular expressions, and structural search

Demo of how to search code three different ways with Sourcegraph