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
5---
6
7## Syntax Overview
8
9A query is made up of expressions. An **expression** can be:
10- A negation (e.g., `-`),
11- A field (e.g., `repo:`).
12- A grouping (e.g., parentheses `()`),
13
14Logical `OR` operations combine multiple expressions. The **`AND` operator is implicit**, meaning multiple expressions written together will be automatically treated as `AND`.
15
16---
17
18## Query Components
19
20### 1. **Fields**
21
22Fields restrict your query to specific criteria. Here's a list of fields and their usage:
23
24| Field | Aliases | Values | Description | Examples |
25|--------------|---------|------------------------|------------------------------------------------------------|----------------------------------------|
26| `archived:` | `a:` | `yes` or `no` | Filters archived repositories. | `archived:yes` |
27| `case:` | `c:` | `yes`, `no`, or `auto` | Matches case-sensitive or insensitive text. | `case:yes content:"Foo"` |
28| `content:` | `c:` | Text (string or regex) | Searches content of files. | `content:"search term"` |
29| `file:` | `f:` | Text (string or regex) | Searches file names. | `file:"main.go"` |
30| `fork:` | `f:` | `yes` or `no` | Filters forked repositories. | `fork:no` |
31| `lang:` | `l:` | Text | Filters by programming language. | `lang:python` |
32| `public:` | | `yes` or `no` | Filters public repositories. | `public:yes` |
33| `regex:` | | Regex pattern | Matches content using a regular expression. | `regex:/foo.*bar/` |
34| `repo:` | `r:` | Text (string or regex) | Filters repositories by name. | `repo:"github.com/user/project"` |
35| `sym:` | | Text | Searches for symbol names. | `sym:"MyFunction"` |
36| `branch:` | `b:` | Text | Searches within a specific branch. | `branch:main` |
37| `type:` | `t:` | `filematch`, `filename`, `file`, or `repo` | Limits result types. | `type:filematch` |
38
39---
40
41### 2. **Negation**
42
43Negate an expression using the `-` symbol.
44
45#### Examples:
46- Exclude a repository:
47 ```plaintext
48 -repo:"github.com/example/repo"
49 ```
50- Exclude a language:
51 ```plaintext
52 -lang:javascript
53 ```
54
55---
56
57### 3. **Grouping**
58
59Group queries using parentheses `()` to create complex logic.
60
61#### Examples:
62- Match either of two repositories:
63 ```plaintext
64 (repo:repo1 or repo:repo2)
65 ```
66- Find test in either python or javascript files:
67 ```plaintext
68 content:test (lang:python or lang:javascript)
69 ```
70
71---
72
73### 4. **Logical Operators**
74
75Use `or` to combine multiple expressions.
76
77#### Examples:
78- Match files in either of two languages:
79 ```plaintext
80 lang:go or lang:java
81 ```
82
83`and` boolean operator is applied automatically when expressions are separated by a space.
84
85---
86
87## Special Query Values
88
89- **Boolean Values**:
90 Use `yes` or `no` for fields like `archived:` or `fork:`.
91
92- **Text Fields**:
93 Text fields (`content:`, `repo:`, etc.) accept:
94 - Strings: `"my text"`
95 - Regular expressions: `/my.*regex/`
96
97- **Escape Characters**:
98 To include special characters, use backslashes (`\`).
99
100#### Examples:
101- Match the string `foo"bar`:
102 ```plaintext
103 content:"foo\"bar"
104 ```
105- Match the regex `foo.*bar`:
106 ```plaintext
107 content:/foo.*bar/
108 ```
109
110---
111
112## Advanced Examples
113
1141. **Search for content in Python files in public repositories**:
115 ```plaintext
116 lang:python public:yes content:"my_function"
117 ```
118
1192. **Exclude archived repositories and match a regex**:
120 ```plaintext
121 archived:no regex:/error.*handler/
122 ```
123
1243. **Find files named `README.md` in forks**:
125 ```plaintext
126 file:"README.md" fork:yes
127 ```
128
1294. **Search for a specific branch**:
130 ```plaintext
131 branch:main content:"TODO"
132 ```
133
1345. **Combine multiple fields**:
135 ```plaintext
136 (repo:"github.com/example" or repo:"github.com/test") and lang:go
137 ```
138
139---
140
141## Tips
142
1431. **Combine Filters**: You can combine as many fields as needed. For instance:
144 ```plaintext
145 repo:"github.com/example" lang:go content:"init"
146 ```
147
1482. **Use Regular Expressions**: Make complex content searches more powerful:
149 ```plaintext
150 content:/func\s+\w+\s*\(/
151 ```
152
1533. **Case Sensitivity**: Use `case:yes` for exact matches:
154 ```plaintext
155 case:yes content:"ExactMatch"
156 ```
157
1584. **Match Specific File Types**:
159 ```plaintext
160 file:".*\.go" content:"package main"
161 ```
162
163### EBNF Summary
164
165```ebnf
166query = expression , { "or" , expression } ;
167
168expression = negation
169 | grouping
170 | field ;
171
172negation = "-" , expression ;
173
174grouping = "(" , query , ")" ;
175
176field = ( ( "archived:" | "a:" ) , boolean )
177 | ( ( "case:" | "c:" ) , ("yes" | "no" | "auto") )
178 | ( ( "content:" | "c:" ) , text )
179 | ( ( "file:" | "f:" ) , text )
180 | ( ( "fork:" | "f:" ) , boolean )
181 | ( ( "lang:" | "l:" ) , text )
182 | ( ( "public:" ) , boolean )
183 | ( ( "regex:" ) , text )
184 | ( ( "repo:" | "r:" ) , text )
185 | ( ( "sym:" ) , text )
186 | ( ( "branch:" | "b:" ) , text )
187 | ( ( "type:" | "t:" ) , type );
188
189boolean = "yes" | "no" ;
190text = string | regex ;
191string = '"' , { character | escape } , '"' ;
192regex = '/' , { character | escape } , '/' ;
193
194type = "filematch" | "filename" | "file" | "repo" ;
195```