|
| 1 | +--- |
| 2 | +title: Understanding GitHub Code Search (beta) syntax |
| 3 | +intro: 'You can build search queries that return the results you want with specialized code qualifiers, regular expressions, and boolean operations.' |
| 4 | +allowTitleToDifferFromFilename: true |
| 5 | +versions: |
| 6 | + feature: github-code-search |
| 7 | +topics: |
| 8 | + - GitHub search |
| 9 | +--- |
| 10 | + |
| 11 | +{% note %} |
| 12 | + |
| 13 | +**Note:** {% data reusables.search.code-search-code-view-beta-note %}<br><br> |
| 14 | + |
| 15 | +{% data reusables.search.code-search-link %} {% data reusables.search.code-view-link %} |
| 16 | + |
| 17 | +{% endnote %} |
| 18 | + |
| 19 | +## About the GitHub Code Search query structure |
| 20 | + |
| 21 | +Please note that the search syntax in this article only applies to searching code with the GitHub Code Search (beta). The syntax and qualifiers used when searching for other search types such as issues, pull requests, and wikis works the same way as it does with the classic search on GitHub.com. For more information, see "[Searching on GitHub](/search-github/searching-on-github/index.md)." |
| 22 | + |
| 23 | +Search queries consist of search terms, consisting of text you want to search for, and qualifiers, which narrow down the search. |
| 24 | + |
| 25 | +A bare term with no qualifiers will match either the content of a file or the file's path. |
| 26 | + |
| 27 | +For example, the following query: |
| 28 | + |
| 29 | +``` |
| 30 | +http-push |
| 31 | +``` |
| 32 | + |
| 33 | +The above query will match the file `docs/http-push.txt`, even if it doesn't contain the term `http-push`. It will also match a file called `example.txt` if it contains the term `http-push`. |
| 34 | + |
| 35 | +You can enter multiple terms separated by whitespace to search for documents that satisfy both terms. |
| 36 | + |
| 37 | +For example, the following query: |
| 38 | + |
| 39 | +``` |
| 40 | +sparse index |
| 41 | +``` |
| 42 | + |
| 43 | +The search results would include all documents containing both the terms `sparse` and `index`, in any order. As examples, it would match a file containing `SparseIndexVector`, or even the phrase `index for sparse trees`. |
| 44 | + |
| 45 | +Searching for multiple terms separated by whitespace is the equivalent to the search `hello AND world`. Other boolean operations, such as `hello OR world`, are also supported in GitHub Code Search (beta). For more information about boolean operations, see "[Using boolean operations](#using-boolean-operations)." |
| 46 | + |
| 47 | +GitHub Code Search (beta) also supports searching for an exact string, including whitespace. For more information, see "[Query for an exact match](#query-for-an-exact-match)." |
| 48 | + |
| 49 | +You can narrow your code search with specialized qualifiers, such as `repo:`, `language:` and `path:`. For more information on the qualifiers you can use in GitHub Code Search (beta), see "[Using qualifiers](#using-qualifiers)." |
| 50 | + |
| 51 | +You can also use regular expressions in your searches by surrounding the expression in slashes. For more information on using regular expressions, see "[Using regular expressions](#using-regular-expressions)." |
| 52 | + |
| 53 | +## Query for an exact match |
| 54 | + |
| 55 | +To search for an exact string, including whitespace, you can surround the string in quotes. For example: |
| 56 | + |
| 57 | +``` |
| 58 | +"sparse index" |
| 59 | +``` |
| 60 | + |
| 61 | +To search for a phrase containing a quotation mark, you can escape the quotation mark using a backslash. For example, to find the exact string `name = "tensorflow"`, you can search: |
| 62 | + |
| 63 | +``` |
| 64 | +"name = \"tensorflow\"" |
| 65 | +``` |
| 66 | + |
| 67 | +You can also use quoted strings in qualifiers, for example: |
| 68 | + |
| 69 | +``` |
| 70 | +path: git language: "protocol buffers" |
| 71 | +``` |
| 72 | + |
| 73 | +## Using boolean operations |
| 74 | + |
| 75 | +The GitHub Code Search (beta) supports boolean expressions. You can use the operators `AND`, `OR`, and `NOT` to combine search terms. |
| 76 | + |
| 77 | +By default, adjacent terms separated by whitespace are equivalent to using the `AND` operator. For example, the search query `sparse index` is the same as `sparse AND index`, meaning that the search results will include all documents containing both the terms `sparse` and `index`, in any order. |
| 78 | + |
| 79 | +To search for documents containing either one term or the other, you can use the `OR` operator. For example, the following query will match documents containing either `sparse` or `index`: |
| 80 | + |
| 81 | +``` |
| 82 | +sparse OR index |
| 83 | +``` |
| 84 | + |
| 85 | +To exclude files from your search results, you can use the `NOT` operator. For example, to exclude file in the `__testing__` directory, you can search: |
| 86 | + |
| 87 | +``` |
| 88 | +"fatal error" NOT path:__testing__ |
| 89 | +``` |
| 90 | + |
| 91 | +You can use parentheses to express more complicated boolean expressions. For example: |
| 92 | + |
| 93 | +``` |
| 94 | +(language:ruby OR language:python) AND NOT path:"/tests/" |
| 95 | +``` |
| 96 | + |
| 97 | +## Using qualifiers |
| 98 | + |
| 99 | +You can use specialized keywords to qualify your search. |
| 100 | + |
| 101 | +### Repository qualifier |
| 102 | + |
| 103 | +To search within a repository, use the `repo:` qualifier. You must provide the full repository name, including the owner. For example: |
| 104 | + |
| 105 | +``` |
| 106 | +repo:github/linguist |
| 107 | +``` |
| 108 | + |
| 109 | +To search within a set of repositories, you can combine multiple `repo:` qualifiers with the boolean operator `OR`. For example: |
| 110 | + |
| 111 | +``` |
| 112 | +repo:github/linguist OR repo:tree-sitter/tree-sitter |
| 113 | +``` |
| 114 | + |
| 115 | +{% note %} |
| 116 | + |
| 117 | +**Note:** GitHub Code Search does not currently support regular expressions or partial matching for repository names, so you will have to type the entire repository name (including the user prefix) for the `repo:` qualifier to work. |
| 118 | + |
| 119 | +{% endnote %} |
| 120 | + |
| 121 | +### Organization and user qualifiers |
| 122 | + |
| 123 | +To search for files within an organization, use the `org:` qualifier. For example: |
| 124 | + |
| 125 | +``` |
| 126 | +org:github |
| 127 | +``` |
| 128 | + |
| 129 | +To search for files within an organization, use the `user:` qualifier. For example: |
| 130 | + |
| 131 | +``` |
| 132 | +user:octocat |
| 133 | +``` |
| 134 | + |
| 135 | +{% note %} |
| 136 | + |
| 137 | +**Note:** GitHub Code Search does not currently support regular expressions or partial matching for organization or user names, so you will have to type the entire organization or user name for the qualifier to work. |
| 138 | + |
| 139 | +{% endnote %} |
| 140 | + |
| 141 | + |
| 142 | +### Language qualifier |
| 143 | + |
| 144 | +To narrow down to a specific languages, use the `language:` qualifier. For example: |
| 145 | + |
| 146 | +``` |
| 147 | +language: ruby OR language:cpp OR language:csharp |
| 148 | +``` |
| 149 | + |
| 150 | +For a complete list of supported language names, see [languages.yaml](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml) in [github/linguist](https://github.com/github/linguist). If your preferred language is not on the list, you can open a pull request to add it. |
| 151 | + |
| 152 | +### Path qualifier |
| 153 | + |
| 154 | +TBD |
| 155 | + |
| 156 | + |
| 157 | +### Symbol qualifier |
| 158 | + |
| 159 | +TBD |
| 160 | + |
| 161 | +### Content qualifier |
| 162 | + |
| 163 | +By default, bare terms search both paths and file content. To restrict a search to strictly match the content of a file and not file paths, use the `content:` qualifier. For example: |
| 164 | + |
| 165 | +``` |
| 166 | +content:README.md |
| 167 | +``` |
| 168 | + |
| 169 | +This query would only match files containing the term `README.md`, rather than matching files named `README.md`. |
| 170 | + |
| 171 | + |
| 172 | +### Is qualifier |
| 173 | + |
| 174 | +To filter based on document properties, you can use the `is:` qualifier. At this time, the only value supported in this qualifier is `archived`, which restricts the search to archived repositories. For example: |
| 175 | + |
| 176 | +``` |
| 177 | +path:/MIT.txt is:archived |
| 178 | +``` |
| 179 | + |
| 180 | +Note that the `is:` qualifier can be inverted with the `NOT` operator. To search for non-archived repositories, you can search: |
| 181 | + |
| 182 | +``` |
| 183 | +log4j NOT is:archived |
| 184 | +``` |
| 185 | + |
| 186 | +## Using regular expressions |
| 187 | + |
| 188 | +GitHub Code Search (beta) supports regular expressions to search for patterns in your code. You can use regular expressions in bare search terms as well as within many qualifiers, by surrounding the regex expression in backslashes. |
| 189 | + |
| 190 | +For example, to search for the regular expression `sparse.*index`, you would use: |
| 191 | + |
| 192 | +``` |
| 193 | +/sparse.*index/ |
| 194 | +``` |
| 195 | + |
| 196 | +Note that you'll have to escape any forward slashes within the regular expression. For example, to search for files within the `App/src` directory, you would use: |
| 197 | + |
| 198 | +``` |
| 199 | +/^App\/src\// |
| 200 | +``` |
| 201 | + |
| 202 | + |
0 commit comments