fork of https://github.com/sourcegraph/zoekt
1# Zoekt Query Language Guide
2
3This guide explains the Zoekt query language, used for searching text within Git repositories. Zoekt queries allow combining multiple filters and expressions using logical operators, negations, and grouping. Here's how to craft queries effectively.
4
5For a brief overview of Zoekt's query syntax, see [these great docs from neogrok](https://neogrok-demo-web.fly.dev/syntax).
6
7---
8
9## Syntax Overview
10
11A query is made up of expressions. An **expression** can be:
12- A negation (e.g., `-`),
13- A field (e.g., `repo:`),
14- A grouping (e.g., parentheses `()`),
15
16Logical `OR` operations combine multiple expressions. The **`AND` operator is implicit**, meaning multiple expressions written together will be automatically treated as `AND`.
17
18---
19
20## Query Components
21
22### 1. **Fields**
23
24Fields restrict your query to specific criteria. Here's a list of fields and their usage:
25
26| Field | Aliases | Values | Description | Examples |
27|--------------|---------|------------------------|------------------------------------------------------------|----------------------------------------|
28| `archived:` | `a:` | `yes` or `no` | Filters archived repositories. | `archived:yes` |
29| `case:` | `c:` | `yes`, `no`, or `auto` | Matches case-sensitive or insensitive text. | `case:yes content:"Foo"` |
30| `content:` | `c:` | Text (string or regex) | Searches content of files. | `content:"search term"` |
31| `file:` | `f:` | Text (string or regex) | Searches file names. | `file:"main.go"` |
32| `fork:` | `f:` | `yes` or `no` | Filters forked repositories. | `fork:no` |
33| `lang:` | `l:` | Text | Filters by programming language. | `lang:python` |
34| `public:` | | `yes` or `no` | Filters public repositories. | `public:yes` |
35| `regex:` | | Regex pattern | Matches content using a regular expression. | `regex:/foo.*bar/` |
36| `repo:` | `r:` | Text (string or regex) | Filters repositories by name. | `repo:"github.com/user/project"` |
37| `sym:` | | Text | Searches for symbol names. | `sym:"MyFunction"` |
38| `branch:` | `b:` | Text | Searches within a specific branch. | `branch:main` |
39| `type:` | `t:` | `filematch`, `filename`, `file`, or `repo` | Limits result types. | `type:filematch` |
40
41---
42
43### 2. **Negation**
44
45Negate an expression using the `-` symbol.
46
47#### Examples:
48- Exclude a repository:
49 ```plaintext
50 -repo:"github.com/example/repo"
51 ```
52- Exclude a language:
53 ```plaintext
54 -lang:javascript
55 ```
56
57---
58
59### 3. **Grouping**
60
61Group queries using parentheses `()` to create complex logic.
62
63#### Examples:
64- Match either of two repositories:
65 ```plaintext
66 (repo:repo1 or repo:repo2)
67 ```
68- Find test in either python or javascript files:
69 ```plaintext
70 content:test (lang:python or lang:javascript)
71 ```
72
73---
74
75### 4. **Logical Operators**
76
77Use `or` to combine multiple expressions.
78
79#### Examples:
80- Match files in either of two languages:
81 ```plaintext
82 lang:go or lang:java
83 ```
84
85`and` boolean operator is applied automatically when expressions are separated by a space.
86
87---
88
89## Special Query Types
90
91### Filtering by Repository Type
92
93Zoekt supports filtering repositories by various attributes:
94
95```plaintext
96public:yes archived:no fork:no
97```
98
99This finds repositories that are public, not archived, and not forks.
100
101### Result Type Control
102
103The `type:` operator controls what kind of results are returned:
104
105```plaintext
106type:repo content:config
107```
108
109This returns repository names instead of file matches. Valid values include:
110- `filematch` - Returns file content matches (default)
111- `filename` - Returns only matching filenames
112- `repo` - Returns only repository names
113
114`type:` applies to the whole expression in its current scope, including `or`
115clauses. For example, `type:repo foo or bar` is equivalent to
116`type:repo (foo or bar)`. Use parentheses to scope `type:` to only one branch,
117for example `(type:repo foo) or bar`.
118
119---
120
121## Special Query Values
122
123- **Boolean Values**:
124 Use `yes` or `no` for fields like `archived:` or `fork:`.
125
126- **Text Fields**:
127 Text fields (`content:`, `repo:`, etc.) accept:
128 - Strings: `"my text"`
129 - Regular expressions: `/my.*regex/`
130
131- **Escape Characters**:
132 To include special characters, use backslashes (`\`).
133
134#### Examples:
135- Match the string `foo"bar`:
136 ```plaintext
137 content:"foo\"bar"
138 ```
139- Match the regex `foo.*bar`:
140 ```plaintext
141 content:/foo.*bar/
142 ```
143
144---
145
146## Case Sensitivity
147
148Zoekt supports three case sensitivity modes:
149
150- `case:yes` - Exact case matching
151- `case:no` - Case-insensitive matching
152- `case:auto` - Automatically detect based on pattern (default)
153
154In auto mode, if the pattern contains uppercase letters, the search will be
155case-sensitive; otherwise, it will be case-insensitive.
156
157---
158
159## Advanced Examples
160
1611. **Search for content in Python files in public repositories**:
162 ```plaintext
163 lang:python public:yes content:"my_function"
164 ```
165
1662. **Exclude archived repositories and match a regex**:
167 ```plaintext
168 archived:no regex:/error.*handler/
169 ```
170
1713. **Find files named `README.md` in forks**:
172 ```plaintext
173 file:"README.md" fork:yes
174 ```
175
1764. **Search for a specific branch**:
177 ```plaintext
178 branch:main content:"TODO"
179 ```
180
1815. **Combine multiple fields**:
182 ```plaintext
183 (repo:"github.com/example" or repo:"github.com/test") and lang:go
184 ```
185
186---
187
188## Tips
189
1901. **Combine Filters**: You can combine as many fields as needed. For instance:
191 ```plaintext
192 repo:"github.com/example" lang:go content:"init"
193 ```
194
1952. **Use Regular Expressions**: Make complex content searches more powerful:
196 ```plaintext
197 content:/func\s+\w+\s*\(/
198 ```
199
2003. **Case Sensitivity**: Use `case:yes` for exact matches:
201 ```plaintext
202 case:yes content:"ExactMatch"
203 ```
204
2054. **Match Specific File Types**:
206 ```plaintext
207 file:".*\.go" content:"package main"
208 ```
209
210### EBNF Summary
211
212```ebnf
213query = expression , { "or" , expression } ;
214
215expression = negation
216 | grouping
217 | field ;
218
219negation = "-" , expression ;
220
221grouping = "(" , query , ")" ;
222
223field = ( ( "archived:" | "a:" ) , boolean )
224 | ( ( "case:" | "c:" ) , ("yes" | "no" | "auto") )
225 | ( ( "content:" | "c:" ) , text )
226 | ( ( "file:" | "f:" ) , text )
227 | ( ( "fork:" | "f:" ) , boolean )
228 | ( ( "lang:" | "l:" ) , text )
229 | ( ( "public:" ) , boolean )
230 | ( ( "regex:" ) , text )
231 | ( ( "repo:" | "r:" ) , text )
232 | ( ( "sym:" ) , text )
233 | ( ( "branch:" | "b:" ) , text )
234 | ( ( "type:" | "t:" ) , type );
235
236boolean = "yes" | "no" ;
237text = string | regex ;
238string = '"' , { character | escape } , '"' ;
239regex = '/' , { character | escape } , '/' ;
240
241type = "filematch" | "filename" | "file" | "repo" ;
242```