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 Values
90
91- **Boolean Values**:
92 Use `yes` or `no` for fields like `archived:` or `fork:`.
93
94- **Text Fields**:
95 Text fields (`content:`, `repo:`, etc.) accept:
96 - Strings: `"my text"`
97 - Regular expressions: `/my.*regex/`
98
99- **Escape Characters**:
100 To include special characters, use backslashes (`\`).
101
102#### Examples:
103- Match the string `foo"bar`:
104 ```plaintext
105 content:"foo\"bar"
106 ```
107- Match the regex `foo.*bar`:
108 ```plaintext
109 content:/foo.*bar/
110 ```
111
112---
113
114## Advanced Examples
115
1161. **Search for content in Python files in public repositories**:
117 ```plaintext
118 lang:python public:yes content:"my_function"
119 ```
120
1212. **Exclude archived repositories and match a regex**:
122 ```plaintext
123 archived:no regex:/error.*handler/
124 ```
125
1263. **Find files named `README.md` in forks**:
127 ```plaintext
128 file:"README.md" fork:yes
129 ```
130
1314. **Search for a specific branch**:
132 ```plaintext
133 branch:main content:"TODO"
134 ```
135
1365. **Combine multiple fields**:
137 ```plaintext
138 (repo:"github.com/example" or repo:"github.com/test") and lang:go
139 ```
140
141---
142
143## Tips
144
1451. **Combine Filters**: You can combine as many fields as needed. For instance:
146 ```plaintext
147 repo:"github.com/example" lang:go content:"init"
148 ```
149
1502. **Use Regular Expressions**: Make complex content searches more powerful:
151 ```plaintext
152 content:/func\s+\w+\s*\(/
153 ```
154
1553. **Case Sensitivity**: Use `case:yes` for exact matches:
156 ```plaintext
157 case:yes content:"ExactMatch"
158 ```
159
1604. **Match Specific File Types**:
161 ```plaintext
162 file:".*\.go" content:"package main"
163 ```
164
165### EBNF Summary
166
167```ebnf
168query = expression , { "or" , expression } ;
169
170expression = negation
171 | grouping
172 | field ;
173
174negation = "-" , expression ;
175
176grouping = "(" , query , ")" ;
177
178field = ( ( "archived:" | "a:" ) , boolean )
179 | ( ( "case:" | "c:" ) , ("yes" | "no" | "auto") )
180 | ( ( "content:" | "c:" ) , text )
181 | ( ( "file:" | "f:" ) , text )
182 | ( ( "fork:" | "f:" ) , boolean )
183 | ( ( "lang:" | "l:" ) , text )
184 | ( ( "public:" ) , boolean )
185 | ( ( "regex:" ) , text )
186 | ( ( "repo:" | "r:" ) , text )
187 | ( ( "sym:" ) , text )
188 | ( ( "branch:" | "b:" ) , text )
189 | ( ( "type:" | "t:" ) , type );
190
191boolean = "yes" | "no" ;
192text = string | regex ;
193string = '"' , { character | escape } , '"' ;
194regex = '/' , { character | escape } , '/' ;
195
196type = "filematch" | "filename" | "file" | "repo" ;
197```