
In his story “The Library of Babel,” Argentine writer and librarian Jorge Luis Borges detailed a possibly infinite library that contains a superabundance of books. The trouble is that there is no order to this vast amount of information, so — ironically — the books are rendered effectively useless to those readers searching for knowledge, and the librarians are left in a state of intense despair. 

In our everyday life, we are likely familiar with well organized libraries in our communities, and may be quite adept at using search engines to find information online. When it comes to information outside of textual data — like searching for the code that runs software — there are still opportunities for innovation and improved indexing. While programmers may be well served through reading and learning from repositories of software they know and can access, they may be unable to search code they don’t yet know about or search across large and multiple code bases. Without the ability to meaningfully search code to understand how programs work, and to build on these past efforts towards more powerful software, the ability for developers to continually innovate may have diminishing returns.

Fortunately, humans have been working on indexing and searching across stores of knowledge for a long time — and how to address Borges’s infinite library — even in terms of software. Here, we’ll discuss a brief history of indexing and search across written data, and then consider the recent advances in code search from the last several decades. As we continue to make advances in code indexing and search, more people will have the access needed to effectively understand and create technology, and emerging and expert developers alike will be able to learn from existing code and, in turn, contribute code in service to their communities. 

## Analog and digital search

Across the written record, people have developed ways to find relevant information beginning with tables of contents two millennia ago, alphabetized topics or concordances in the 5th century, and the book index in the 13th century. Physical libraries, too, have a long history of information architecture to support the retrieval of relevant knowledge: in the 16th century, Swiss Polymath Konrad Gessner used paper slips to organize topics; the mid-19th century saw the introduction of ledger books; and by the 1870s physical card catalogs became commonplace in the United States and Britain. 

Analog knowledge indexing has paved the way for digital search engines that we use to rapidly search across websites and media today. As we continue to create, document, and share knowledge, we need to be able to continue to search for and find knowledge that is relevant to us from an ever-increasing volume of information, so that we too can participate in knowledge production. 

## Searching code, the beginnings

Like textual information, computer code is a site where information is stored. As more software is developed and code is created, we need to innovate the way we search for and retrieve code so that we can participate effectively in understanding and creating technology. Tools to search computer code and digital file systems have been developed alongside innovations in technology. 

Bell Labs was an early pioneer in text-based computer search, being the institution behind both `grep` and Cscope. In 1973, Ken Thompson wrote the command-line utility `grep`, which is a tool that allows users to search plain-text data sets for lines that match a given regular expression. The first formation of the tool was developed in order to support Lee E. McMahon’s research project of determining authorship of individual texts within the Federalist Papers via statistical language analysis, and was originally written by Thompson in PDP-11 assembly language. While `grep` has implications across all digital text search, and is not limited to code search, it is an important building block of later tools designed specifically to search code bases.

By the 1980s, Bell Labs had a large C codebase and Joe Steffen began writing a tool that would later be called Cscope in order to aid his own work. Beginning with shell scripts of `grep` and `sed` commands, Cscope eventually would become a C program with a graphical user interface. Because it led to such an increase in productivity across the computation teams at Bell Labs, Cscope was brought into the official AT&T Unix distribution.

## Searching within operating systems

Today, we are accustomed to being able to search within our graphical operating systems and to find lines of code in our IDEs, but these everyday experiences were not always possible. 

In 1991, Microsoft was working on a technology project with the code name Cairo, predating Windows 95. Within the Cairo operating system was a piece of technology called the Object File System, which would later become known as WinFS. The Object File System organized the data within the filesystem into a collection of objects in a strongly typed schema, providing a human readable interface so that users could search across files. Over time, this project became the backbone of file indexing and search within Windows, doing much of the backend work for users to be able to find files effectively. The Object File System also offered developers the ability to hook into this functionality via APIs.

Linux, too, would benefit from search innovation as early as 1994. Two Norwegian students by the names of Arne Georg Gleditsch and Per Kristian Gjermshus were learning about Linux architecture when they began writing a program to display Linux files through a web browser so that they could click on variables and inspect how they were used. As they understood that others working on the Linux kernel were also interested in this project, they posted it on SourceForge early in their development process to support collaboration. Today’s stable version of LXR — or Linux Cross-Referencer — indexes source code and provides code comprehension through web-based browsing of code. This provides definition and usage links to any identifier within the code base. LXR is such a popular tool because Linux enjoys a high number of contributors who need to familiarize themselves with the codebase quickly. 

## Innovating on search

As search tools advanced, implementations continued to be built on top of existing tools. Expanding on `grep`, [agrep](https://github.com/Wikinaut/agrep) added fuzzy search — or _approximate_ matches — to text string- and regex-matching search (hence, “approximate” `grep`). The agrep tool was developed between 1988 and 1991 by Sun Wu and Udi Manber at the University of Arizona. Implementing the methods provided by the Levenshtein algorithm to search text files, agrep interprets relatively simple patterns, but its benefits over `grep` are that it can find similar terms and is often faster. 

Extending on approximate matching and developed by Ville Laurikari, [TRE](https://laurikari.net/tre/) is a command line search tool that offers greater functionality including allowing full regexps of any length, which can be used on Linux via the `tre-agrep` command. The work done on agrep served as a crucial foundation for GLIMPSE (GLobal IMPlicit SEarch), a tool for searching through entire file systems and first [described in a paper](https://www.usenix.org/conference/usenix-winter-1994-technical-conference/glimpse-tool-search-through-entire-file-systems) published in 1994 by Manber and Wu. From GLIMPSE, [Webglimpse](https://web.archive.org/web/20191001112623/http://webglimpse.net/) was developed, which provided developers with a way to add search capability to their web projects.

In the 2000s, Mozilla created a [cross reference tool](https://web.archive.org/web/20080513070520/http://mxr.mozilla.org/) to display and search Mozilla source code built from a fork of LXR with free-text search implemented using GLIMPSE. This search tool was first called MXR (Mozilla Cross Reference), later DXR (Dehydra Cross Reference), and is currently operative as [Searchfox](https://searchfox.org/). Initially written for code navigation across C++ and JavaScript, today it also supports Rust. 

Many search tools would eventually extend the functionality of Apache Lucene, an open-source search engine library originally written in Java by Doug Cutting in 1999. Providing functionality to implement internet search engines as well as local search, Lucene offers approximate search and can be used to generate recommendations as well. The enterprise search server Elasticsearch is notably built off of Lucene, and both [GitHub](https://www.elastic.co/customers/github) and [GitLab](https://about.gitlab.com/blog/2019/03/20/enabling-global-search-elasticsearch-gitlab-com/) use Elasticsearch to enable code search across their code host platforms. 

Also built on Apache Lucene is [OpenGrok](https://oracle.github.io/opengrok/), which is an open-source project written in Java and maintained by Oracle. Originally developed by [Chandan B.N.](https://github.com/oracle/opengrok/wiki/Story-of-OpenGrok), OpenGrok offers fast code search as well as a cross reference engine allowing developers to navigate their source tree. OpenGrok is very popular and actively maintained today. 

## The future of code search 

There are many code search efforts today in active development that gesture toward what developers may expect from code search in the future. Some of these include closed source tools like Google’s internal search tool, making its large code base more accessible to those working on it. The work on Google’s code search began with gsearch by Jeff Dean in the early 2000s, which offered a productivity boost for developers and made large-scale refactoring easier. In 2010, Steve Yegge led the development of Grok at Google for code comprehension; a version of Grok was eventually open-sourced as Kythe in 2015 and is actively under development. Google Code Search, led by Russ Cox, was a free beta public product that debuted in Google Labs in 2006 but was shut down in 2011. There currently is a [publicly re-released](https://cs.opensource.google/) version that debuted in 2020 for use exclusively with Google open source software and Google Cloud Source Repositories.

Founded in 2013 by Quinn Slack and Beyang Liu, Sourcegraph is open core software that offers universal code search across large code bases. Currently used by many enterprise companies as on-premises software, Sourcegraph is also available as [Sourcegraph cloud](https://sourcegraph.com), which enables developers to search across many publicly indexed open source repositories. Sourcegraph’s [long-term mission](https://handbook.sourcegraph.com/strategy-goals/strategy) is to help more people code, and, as we have seen with indexing books, being able to search across code can help more people understand others’ code and write their own code more effectively. 

There is continued interest in the code search space. GitHub, the popular code hosting platform that is a part of Microsoft, announced at the end of 2021 that it was developing improved code search capabilities. Their intention is to improve developer productivity. Investors are also interested in the value that code search can bring. Mintlify, co-founded by Hahnbee Lee and Han Wang, raised a pre-seed round in 2022 and offers a “search engine in your code base” through leveraging AI to help developers search code.

As the number of code repositories increasingly resembles Borges’s infinite library, it is more apparent that we need to be able to meaningfully search across this form of knowledge, just as we do with any other text. User-friendly, sophisticated code search and indexing can allow developers to innovate effectively, learn from and build off of existing code libraries, and quickly onboard onto existing software projects. Ultimately, being able to search code and search it well enables more people to build software through increased coding literacy and access to knowledge. 


Code search history

A history of code search, from libraries to Google, Sourcegraph, and GitHub

A short history of code search


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.

<Highlighter
input='repo:repository-path'
matcher='repository-path'
/>

<Highlighter
input='repo:regular-pattern'
matcher='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`.

<Highlighter
input='repo:repository-path repo:contains.file(file-path)'
matcher='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`.

<Highlighter
input='repo:repo-path repo:contains.content(your-content)'
matcher='your-content'
/> 

<Highlighter
input='repo:repo-path repo:contains.content(regular-pattern)'
matcher='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. 

<Highlighter
input='lang:programming-language'
matcher='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.

<Highlighter
input='-lang:programming-language'
matcher='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`

<Highlighter
input='before:time-period
after:time-period'
matcher='time-period'
/> 

Sometimes the time period can be relative, like `last week`, `last year`, `3 months ago` or absolute, in several formats including `{month} {day} {year}` (example: `february 10 2021`), `dd/mm/yyyy`, and ISO format `yyyy-mm-dd`.

<Highlighter
input='before:last week'
matcher='last week'
/> 

<Highlighter
input='after:february 10 2021'
matcher='february 10 2021'
/> 

<Highlighter
input='before:02/01/2019'
matcher='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.

<Highlighter
input='archived:yes'
matcher='yes'
/> 

<Highlighter
input='archived:no'
matcher='no'
/> 

<Highlighter
input='archived:only'
matcher='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.

<Highlighter
input='case:yes'
matcher='yes'
/> 

<Highlighter
input='case:no'
matcher='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.

<Highlighter
input='type:commit|path|diff|symbol|repo|file'
matcher='commit|path|diff|symbol|repo|file'
/> 

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.
* `path` — restricts terms to matching filenames only (not file contents).
* `diff` — show [diffs](https://git-scm.com/docs/git-diff), or changes, within a repository.
* `repo` — repositories available to you.
* `file` — restricts terms to matching file contents only (not filenames).
* `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.

<Highlighter
input='message:commit-message'
matcher='commit-message'
/> 

<Highlighter
input='message:string-regex-pattern'
matcher='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.

<Highlighter
input='author:author-name'
matcher='author-name'
/> 

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

<Highlighter
input='-author:author-name'
matcher='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.

<Highlighter
input='count:number|all'
matcher='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.

<Highlighter
input='fork:yes|no|only'
matcher='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`).

<Highlighter
input='timeout:time-duration-with-unit'
matcher='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.

<Highlighter
input='visibility:any|private|public'
matcher='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