Skip to content

Commit aac88a6

Browse files
brendan-kellambrendan-kellam
committed
update docs and remove uneeded test file
1 parent d9ff676 commit aac88a6

3 files changed

Lines changed: 143 additions & 115 deletions

File tree

‎docs/docs/features/search/syntax-reference.mdx‎

Lines changed: 31 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,32 +4,51 @@ title: Writing search queries
44

55
Sourcebot uses a powerful regex-based query language that enabled precise code search within large codebases.
66

7-
87
## Syntax reference guide
98

10-
Queries consist of space-separated regular expressions. Wrapping expressions in `""` combines them. By default, a file must have at least one match for each expression to be included.
9+
Queries consist of space-separated search patterns that are matched against file contents. A file must have at least one match for each expression to be included. Queries can optionally contain search filters to further refine the search results.
10+
11+
## Keyword search (default)
12+
13+
Keyword search matches search patterns exactly in file contents. Wrapping search patterns in `""` combines them as a single expression.
1114

1215
| Example | Explanation |
1316
| :--- | :--- |
14-
| `foo` | Match files with regex `/foo/` |
15-
| `foo bar` | Match files with regex `/foo/` **and** `/bar/` |
16-
| `"foo bar"` | Match files with regex `/foo bar/` |
17+
| `foo` | Match files containing the keyword `foo` |
18+
| `foo bar` | Match files containing both `foo` **and** `bar` |
19+
| `"foo bar"` | Match files containing the phrase `foo bar` |
20+
| `"foo \"bar\""` | Match files containing `foo "bar"` exactly (escaped quotes) |
21+
22+
## Regex search
1723

18-
Multiple expressions can be or'd together with `or`, negated with `-`, or grouped with `()`.
24+
Toggle the regex button (`.*`) in the search bar to interpret search patterns as regular expressions.
1925

2026
| Example | Explanation |
2127
| :--- | :--- |
22-
| `foo or bar` | Match files with regex `/foo/` **or** `/bar/` |
23-
| `foo -bar` | Match files with regex `/foo/` but **not** `/bar/` |
24-
| `foo (bar or baz)` | Match files with regex `/foo/` **and** either `/bar/` **or** `/baz/` |
28+
| `foo` | Match files with regex `/foo/` |
29+
| `foo.*bar` | Match files with regex `/foo.*bar/` (foo followed by any characters, then bar) |
30+
| `^function\s+\w+` | Match files with regex `/^function\s+\w+/` (function at start of line, followed by whitespace and word characters) |
31+
| `"foo bar"` | Match files with regex `/foo bar/`. Quotes are not matched. |
2532

26-
Expressions can be prefixed with certain keywords to modify search behavior. Some keywords can be negated using the `-` prefix.
33+
## Search filters
34+
35+
Search queries (keyword or regex) can include multiple search filters to further refine the search results. Some filters can be negated using the `-` prefix.
2736

2837
| Prefix | Description | Example |
2938
| :--- | :--- | :--- |
3039
| `file:` | Filter results from filepaths that match the regex. By default all files are searched. | `file:README` - Filter results to filepaths that match regex `/README/`<br/>`file:"my file"` - Filter results to filepaths that match regex `/my file/`<br/>`-file:test\.ts$` - Ignore results from filepaths match regex `/test\.ts$/` |
31-
| `repo:` | Filter results from repos that match the regex. By default all repos are searched. | `repo:linux` - Filter results to repos that match regex `/linux/`<br/>`-repo:^web/.*` - Ignore results from repos that match regex `/^web\/.*` |
40+
| `repo:` | Filter results from repos that match the regex. By default all repos are searched. | `repo:linux` - Filter results to repos that match regex `/linux/`<br/>`-repo:^web/.*` - Ignore results from repos that match regex `/^web\/.*/` |
3241
| `rev:` | Filter results from a specific branch or tag. By default **only** the default branch is searched. | `rev:beta` - Filter results to branches that match regex `/beta/` |
3342
| `lang:` | Filter results by language (as defined by [linguist](https://github.com/github-linguist/linguist/blob/main/lib/linguist/languages.yml)). By default all languages are searched. | `lang:TypeScript` - Filter results to TypeScript files<br/>`-lang:YAML` - Ignore results from YAML files |
3443
| `sym:` | Match symbol definitions created by [universal ctags](https://ctags.io/) at index time. | `sym:\bmain\b` - Filter results to symbols that match regex `/\bmain\b/` |
35-
| `context:` | Filter results to a predefined [search context](/docs/features/search/search-contexts). | `context:web` - Filter results to the web context<br/>`-context:pipelines` - Ignore results from the pipelines context |
44+
| `context:` | Filter results to a predefined [search context](/docs/features/search/search-contexts). | `context:web` - Filter results to the web context<br/>`-context:pipelines` - Ignore results from the pipelines context |
45+
46+
## Boolean operators & grouping
47+
48+
By default, space-separated expressions are and'd together. Using the `or` keyword as well as parentheses `()` can be used to create more complex boolean logic. Parentheses can be negated using the `-` prefix.
49+
50+
| Example | Explanation |
51+
| :--- | :--- |
52+
| `foo or bar` | Match files containing `foo` **or** `bar` |
53+
| `foo (bar or baz)` | Match files containing `foo` **and** either `bar` **or** `baz`. |
54+
| `-(foo) bar` | Match files containing `bar` **and not** `foo`. |

‎packages/queryLanguage/test.ts‎

Lines changed: 0 additions & 46 deletions
This file was deleted.

‎packages/web/src/app/[domain]/components/syntaxReferenceGuide.tsx‎

Lines changed: 112 additions & 57 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ import { useCallback, useRef } from "react";
1515
import { useHotkeys } from "react-hotkeys-hook";
1616
import { useSyntaxGuide } from "./syntaxGuideProvider";
1717
import { CodeSnippet } from "@/app/components/codeSnippet";
18+
import { ExternalLinkIcon, RegexIcon } from "lucide-react";
1819

1920
const LINGUIST_LINK = "https://github.com/github-linguist/linguist/blob/main/lib/linguist/languages.yml";
2021
const CTAGS_LINK = "https://ctags.io/";
@@ -61,70 +62,92 @@ export const SyntaxReferenceGuide = () => {
6162
onOpenChange={handleOpenChange}
6263
>
6364
<DialogContent
64-
className="max-h-[80vh] max-w-[700px] overflow-scroll"
65+
className="max-h-[80vh] max-w-[700px] overflow-scroll gap-2"
6566
>
6667
<DialogHeader>
67-
<DialogTitle>Syntax Reference Guide</DialogTitle>
68+
<DialogTitle>Syntax Reference Guide <Link href="https://docs.sourcebot.dev/docs/features/search/syntax-reference"><ExternalLinkIcon className="inline w-4 h-4 ml-1 mb-1 text-muted-foreground cursor-pointer" /></Link></DialogTitle>
6869
<DialogDescription className="text-sm text-foreground">
69-
Queries consist of space-seperated regular expressions. Wrapping expressions in <CodeSnippet>{`""`}</CodeSnippet> combines them. By default, a file must have at least one match for each expression to be included.
70+
Queries consist of space-separated search patterns that are matched against file contents. A file must have at least one match for each expression to be included. Queries can optionally contain search filters to further refine the search results.
7071
</DialogDescription>
7172
</DialogHeader>
72-
<Table>
73-
<TableHeader>
74-
<TableRow>
75-
<TableHead className="py-2">Example</TableHead>
76-
<TableHead className="py-2">Explanation</TableHead>
77-
</TableRow>
78-
</TableHeader>
79-
<TableBody>
80-
<TableRow>
81-
<TableCell className="py-2"><CodeSnippet>foo</CodeSnippet></TableCell>
82-
<TableCell className="py-2">Match files with regex <CodeSnippet>/foo/</CodeSnippet></TableCell>
83-
</TableRow>
84-
<TableRow>
85-
<TableCell className="py-2"><CodeSnippet>foo bar</CodeSnippet></TableCell>
86-
<TableCell className="py-2">Match files with regex <CodeSnippet>/foo/</CodeSnippet> <b>and</b> <CodeSnippet>/bar/</CodeSnippet></TableCell>
87-
</TableRow>
88-
<TableRow>
89-
<TableCell className="py-2"><CodeSnippet>{`"foo bar"`}</CodeSnippet></TableCell>
90-
<TableCell className="py-2">Match files with regex <CodeSnippet>/foo bar/</CodeSnippet></TableCell>
91-
</TableRow>
92-
</TableBody>
93-
</Table>
9473

95-
<Separator className="my-2"/>
96-
<p className="text-sm">
97-
{`Multiple expressions can be or'd together with `}<CodeSnippet>or</CodeSnippet>, negated with <CodeSnippet>-</CodeSnippet>, or grouped with <CodeSnippet>()</CodeSnippet>.
98-
</p>
99-
<Table>
100-
<TableHeader>
101-
<TableRow>
102-
<TableHead className="py-2">Example</TableHead>
103-
<TableHead className="py-2">Explanation</TableHead>
104-
</TableRow>
105-
</TableHeader>
106-
<TableBody>
107-
<TableRow>
108-
<TableCell className="py-2"><CodeSnippet>foo <Highlight>or</Highlight> bar</CodeSnippet></TableCell>
109-
<TableCell className="py-2">Match files with regex <CodeSnippet>/foo/</CodeSnippet> <b>or</b> <CodeSnippet>/bar/</CodeSnippet></TableCell>
110-
</TableRow>
111-
<TableRow>
112-
<TableCell className="py-2"><CodeSnippet>foo -bar</CodeSnippet></TableCell>
113-
<TableCell className="py-2">Match files with regex <CodeSnippet>/foo/</CodeSnippet> but <b>not</b> <CodeSnippet>/bar/</CodeSnippet></TableCell>
114-
</TableRow>
115-
<TableRow>
116-
<TableCell className="py-2"><CodeSnippet>foo (bar <Highlight>or</Highlight> baz)</CodeSnippet></TableCell>
117-
<TableCell className="py-2">Match files with regex <CodeSnippet>/foo/</CodeSnippet> <b>and</b> either <CodeSnippet>/bar/</CodeSnippet> <b>or</b> <CodeSnippet>/baz/</CodeSnippet></TableCell>
118-
</TableRow>
119-
</TableBody>
120-
</Table>
74+
<div>
75+
<h3 className="text-lg font-semibold mt-4 mb-0">Keyword search (default)</h3>
76+
<p className="text-sm mb-2 mt-0">
77+
Keyword search matches search patterns exactly in file contents. Wrapping search patterns in <CodeSnippet>{`""`}</CodeSnippet> combines them as a single expression.
78+
</p>
79+
<Table>
80+
<TableHeader>
81+
<TableRow>
82+
<TableHead className="py-2">Example</TableHead>
83+
<TableHead className="py-2">Explanation</TableHead>
84+
</TableRow>
85+
</TableHeader>
86+
<TableBody>
87+
<TableRow>
88+
<TableCell className="py-2"><CodeSnippet>foo</CodeSnippet></TableCell>
89+
<TableCell className="py-2">Match files containing the keyword <CodeSnippet>foo</CodeSnippet></TableCell>
90+
</TableRow>
91+
<TableRow>
92+
<TableCell className="py-2"><CodeSnippet>foo bar</CodeSnippet></TableCell>
93+
<TableCell className="py-2">Match files containing both <CodeSnippet>foo</CodeSnippet> <b>and</b> <CodeSnippet>bar</CodeSnippet></TableCell>
94+
</TableRow>
95+
<TableRow>
96+
<TableCell className="py-2"><CodeSnippet>{`"foo bar"`}</CodeSnippet></TableCell>
97+
<TableCell className="py-2">Match files containing the phrase <CodeSnippet>foo bar</CodeSnippet></TableCell>
98+
</TableRow>
99+
<TableRow>
100+
<TableCell className="py-2"><CodeSnippet>{'"foo \\"bar\\""'}</CodeSnippet></TableCell>
101+
<TableCell className="py-2">Match files containing <CodeSnippet>foo &quot;bar&quot;</CodeSnippet> exactly (escaped quotes)</TableCell>
102+
</TableRow>
103+
</TableBody>
104+
</Table>
105+
</div>
106+
107+
<Separator className="my-4"/>
108+
109+
<div>
110+
<h3 className="text-lg font-semibold mt-4 mb-0">Regex search</h3>
111+
<p className="text-sm mb-2 mt-0">
112+
Toggle the <RegexIcon className="inline w-4 h-4 align-middle mx-0.5 border rounded px-0.5 py-0.5" /> button to interpret search patterns as regular expressions.
113+
</p>
114+
<Table>
115+
<TableHeader>
116+
<TableRow>
117+
<TableHead className="py-2">Example</TableHead>
118+
<TableHead className="py-2">Explanation</TableHead>
119+
</TableRow>
120+
</TableHeader>
121+
<TableBody>
122+
<TableRow>
123+
<TableCell className="py-2"><CodeSnippet>foo</CodeSnippet></TableCell>
124+
<TableCell className="py-2">Match files with regex <CodeSnippet>/foo/</CodeSnippet></TableCell>
125+
</TableRow>
126+
<TableRow>
127+
<TableCell className="py-2"><CodeSnippet>foo.*bar</CodeSnippet></TableCell>
128+
<TableCell className="py-2">Match files with regex <CodeSnippet>/foo.*bar/</CodeSnippet> (foo followed by any characters, then bar)</TableCell>
129+
</TableRow>
130+
<TableRow>
131+
<TableCell className="py-2"><CodeSnippet>{`^function\\s+\\w+`}</CodeSnippet></TableCell>
132+
<TableCell className="py-2">Match files with regex <CodeSnippet>/^function\s+\w+/</CodeSnippet> (function at start of line, followed by whitespace and word characters)</TableCell>
133+
</TableRow>
134+
<TableRow>
135+
<TableCell className="py-2"><CodeSnippet>{`"foo bar"`}</CodeSnippet></TableCell>
136+
<TableCell className="py-2">Match files with regex <CodeSnippet>/foo bar/</CodeSnippet>. Quotes are not matched.</TableCell>
137+
</TableRow>
138+
</TableBody>
139+
</Table>
140+
</div>
121141

122-
<Separator className="my-2"/>
123-
<p className="text-sm">
124-
Expressions can be prefixed with certain keywords to modify search behavior. Some keywords can be negated using the <CodeSnippet>-</CodeSnippet> prefix.
125-
</p>
142+
<Separator className="my-4"/>
126143

127-
<Table>
144+
<div>
145+
<h3 className="text-lg font-semibold mt-4 mb-0">Search filters</h3>
146+
<p className="text-sm mb-2 mt-0">
147+
Search queries (keyword or regex) can include multiple search filters to further refine the search results. Some filters can be negated using the <CodeSnippet>-</CodeSnippet> prefix.
148+
</p>
149+
150+
<Table>
128151
<TableHeader>
129152
<TableRow>
130153
<TableHead className="py-2">Prefix</TableHead>
@@ -219,7 +242,39 @@ export const SyntaxReferenceGuide = () => {
219242
</TableCell>
220243
</TableRow>
221244
</TableBody>
222-
</Table>
245+
</Table>
246+
</div>
247+
248+
<Separator className="my-4"/>
249+
250+
<div>
251+
<h3 className="text-lg font-semibold mt-4 mb-0">Boolean operators &amp; grouping</h3>
252+
<p className="text-sm mb-2 mt-0">
253+
By default, space-seperated expressions are and&apos;d together. Using the <CodeSnippet>or</CodeSnippet> keyword as well as parantheses <CodeSnippet>()</CodeSnippet> can be used to create more complex boolean logic. Parantheses can be negated using the <CodeSnippet>-</CodeSnippet> prefix.
254+
</p>
255+
<Table>
256+
<TableHeader>
257+
<TableRow>
258+
<TableHead className="py-2">Example</TableHead>
259+
<TableHead className="py-2">Explanation</TableHead>
260+
</TableRow>
261+
</TableHeader>
262+
<TableBody>
263+
<TableRow>
264+
<TableCell className="py-2"><CodeSnippet>foo <Highlight>or</Highlight> bar</CodeSnippet></TableCell>
265+
<TableCell className="py-2">Match files containing <CodeSnippet>foo</CodeSnippet> <b>or</b> <CodeSnippet>bar</CodeSnippet></TableCell>
266+
</TableRow>
267+
<TableRow>
268+
<TableCell className="py-2"><CodeSnippet>foo (bar <Highlight>or</Highlight> baz)</CodeSnippet></TableCell>
269+
<TableCell className="py-2">Match files containing <CodeSnippet>foo</CodeSnippet> <b>and</b> either <CodeSnippet>bar</CodeSnippet> <b>or</b> <CodeSnippet>baz</CodeSnippet>.</TableCell>
270+
</TableRow>
271+
<TableRow>
272+
<TableCell className="py-2"><CodeSnippet>-(foo) bar</CodeSnippet></TableCell>
273+
<TableCell className="py-2">Match files containing <CodeSnippet>bar</CodeSnippet> <b>and not</b> <CodeSnippet>foo</CodeSnippet>.</TableCell>
274+
</TableRow>
275+
</TableBody>
276+
</Table>
277+
</div>
223278
</DialogContent>
224279
</Dialog>
225280
)

0 commit comments

Comments
 (0)