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---
115
116## Special Query Values
117
118- **Boolean Values**:
119 Use `yes` or `no` for fields like `archived:` or `fork:`.
120
121- **Text Fields**:
122 Text fields (`content:`, `repo:`, etc.) accept:
123 - Strings: `"my text"`
124 - Regular expressions: `/my.*regex/`
125
126- **Escape Characters**:
127 To include special characters, use backslashes (`\`).
128
129#### Examples:
130- Match the string `foo"bar`:
131 ```plaintext
132 content:"foo\"bar"
133 ```
134- Match the regex `foo.*bar`:
135 ```plaintext
136 content:/foo.*bar/
137 ```
138
139---
140
141## Case Sensitivity
142
143Zoekt supports three case sensitivity modes:
144
145- `case:yes` - Exact case matching
146- `case:no` - Case-insensitive matching
147- `case:auto` - Automatically detect based on pattern (default)
148
149In auto mode, if the pattern contains uppercase letters, the search will be
150case-sensitive; otherwise, it will be case-insensitive.
151
152---
153
154## Advanced Examples
155
1561. **Search for content in Python files in public repositories**:
157 ```plaintext
158 lang:python public:yes content:"my_function"
159 ```
160
1612. **Exclude archived repositories and match a regex**:
162 ```plaintext
163 archived:no regex:/error.*handler/
164 ```
165
1663. **Find files named `README.md` in forks**:
167 ```plaintext
168 file:"README.md" fork:yes
169 ```
170
1714. **Search for a specific branch**:
172 ```plaintext
173 branch:main content:"TODO"
174 ```
175
1765. **Combine multiple fields**:
177 ```plaintext
178 (repo:"github.com/example" or repo:"github.com/test") and lang:go
179 ```
180
181---
182
183## Tips
184
1851. **Combine Filters**: You can combine as many fields as needed. For instance:
186 ```plaintext
187 repo:"github.com/example" lang:go content:"init"
188 ```
189
1902. **Use Regular Expressions**: Make complex content searches more powerful:
191 ```plaintext
192 content:/func\s+\w+\s*\(/
193 ```
194
1953. **Case Sensitivity**: Use `case:yes` for exact matches:
196 ```plaintext
197 case:yes content:"ExactMatch"
198 ```
199
2004. **Match Specific File Types**:
201 ```plaintext
202 file:".*\.go" content:"package main"
203 ```
204
205### EBNF Summary
206
207```ebnf
208query = expression , { "or" , expression } ;
209
210expression = negation
211 | grouping
212 | field ;
213
214negation = "-" , expression ;
215
216grouping = "(" , query , ")" ;
217
218field = ( ( "archived:" | "a:" ) , boolean )
219 | ( ( "case:" | "c:" ) , ("yes" | "no" | "auto") )
220 | ( ( "content:" | "c:" ) , text )
221 | ( ( "file:" | "f:" ) , text )
222 | ( ( "fork:" | "f:" ) , boolean )
223 | ( ( "lang:" | "l:" ) , text )
224 | ( ( "public:" ) , boolean )
225 | ( ( "regex:" ) , text )
226 | ( ( "repo:" | "r:" ) , text )
227 | ( ( "sym:" ) , text )
228 | ( ( "branch:" | "b:" ) , text )
229 | ( ( "type:" | "t:" ) , type );
230
231boolean = "yes" | "no" ;
232text = string | regex ;
233string = '"' , { character | escape } , '"' ;
234regex = '/' , { character | escape } , '/' ;
235
236type = "filematch" | "filename" | "file" | "repo" ;
237```