fork of https://github.com/sourcegraph/zoekt
New query docs (#861)
author
Konrad Staniszewski
committer
GitHub
date
(Nov 22, 2024, 12:09 PM +0200)
commit
ee3d17d1
ee3d17d13d4fdeaad412543f6fe841af19836f70
parent
7af9f842
7af9f842568cf8e164cc82561394aa2939f03348
+194
-4
+194
-4
doc/query_syntax.md
+194
-4
doc/query_syntax.md
···
1
-
# Query syntax
1
+
# Zoekt Query Language Guide
2
+
3
+
This 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
+
9
+
A 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
+
14
+
Logical `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
+
22
+
Fields 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
+
43
+
Negate 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
+
59
+
Group 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
+
75
+
Use `or` to combine multiple expressions.
2
76
3
-
Query syntax examples can be found on the index page of a running Zoekt webserver.
4
-
These
5
-
[example queries can also be viewed in the corresponding HTML template](../web/templates.go#L158).
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
+
114
+
1. **Search for content in Python files in public repositories**:
115
+
```plaintext
116
+
lang:python public:yes content:"my_function"
117
+
```
118
+
119
+
2. **Exclude archived repositories and match a regex**:
120
+
```plaintext
121
+
archived:no regex:/error.*handler/
122
+
```
123
+
124
+
3. **Find files named `README.md` in forks**:
125
+
```plaintext
126
+
file:"README.md" fork:yes
127
+
```
128
+
129
+
4. **Search for a specific branch**:
130
+
```plaintext
131
+
branch:main content:"TODO"
132
+
```
133
+
134
+
5. **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
+
143
+
1. **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
+
148
+
2. **Use Regular Expressions**: Make complex content searches more powerful:
149
+
```plaintext
150
+
content:/func\s+\w+\s*\(/
151
+
```
152
+
153
+
3. **Case Sensitivity**: Use `case:yes` for exact matches:
154
+
```plaintext
155
+
case:yes content:"ExactMatch"
156
+
```
157
+
158
+
4. **Match Specific File Types**:
159
+
```plaintext
160
+
file:".*\.go" content:"package main"
161
+
```
162
+
163
+
### EBNF Summary
164
+
165
+
```ebnf
166
+
query = expression , { "or" , expression } ;
167
+
168
+
expression = negation
169
+
| grouping
170
+
| field ;
171
+
172
+
negation = "-" , expression ;
173
+
174
+
grouping = "(" , query , ")" ;
175
+
176
+
field = ( ( "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
+
189
+
boolean = "yes" | "no" ;
190
+
text = string | regex ;
191
+
string = '"' , { character | escape } , '"' ;
192
+
regex = '/' , { character | escape } , '/' ;
193
+
194
+
type = "filematch" | "filename" | "file" | "repo" ;
195
+
```