From 1a5a6e75ca000307ce69eeecf874be3d5fee6ea2 Mon Sep 17 00:00:00 2001
From: Ashraf Khamis <akhamis@gitlab.com>
Date: Wed, 2 Oct 2024 15:42:43 +0000
Subject: [PATCH] Improve exact code and advanced search docs
---
doc/drawers/advanced_search_syntax.md | 57 +++++++++++-----------
doc/drawers/exact_code_search_syntax.md | 24 ++++-----
doc/integration/exact_code_search/zoekt.md | 25 +++++-----
doc/user/search/advanced_search.md | 2 +
doc/user/search/exact_code_search.md | 30 ++++++------
doc/user/search/index.md | 2 +-
6 files changed, 73 insertions(+), 67 deletions(-)
diff --git a/doc/drawers/advanced_search_syntax.md b/doc/drawers/advanced_search_syntax.md
index 275dc26edab88..c02f8f765d00a 100644
--- a/doc/drawers/advanced_search_syntax.md
+++ b/doc/drawers/advanced_search_syntax.md
@@ -7,38 +7,39 @@ source: /doc/user/search/advanced_search.md
# Syntax options
-<!-- markdownlint-disable -->
-
-| Syntax | Description | Example |
-|--------------|---------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `"` | Exact search | [`"gem sidekiq"`](https://gitlab.com/search?group_id=9970&project_id=278964&scope=blobs&search=%22gem+sidekiq%22) |
-| `~` | Fuzzy search | [`J~ Doe`](https://gitlab.com/search?scope=users&search=j%7E+doe) |
-| <code>|</code> | Or | [<code>display | banner</code>](https://gitlab.com/search?group_id=9970&project_id=278964&scope=blobs&search=display+%7C+banner) |
-| `+` | And | [`display +banner`](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=&scope=blobs&search=display+%2Bbanner&snippets=) |
-| `-` | Exclude | [`display -banner`](https://gitlab.com/search?group_id=9970&project_id=278964&scope=blobs&search=display+-banner) |
-| `*` | Partial | [`bug error 50*`](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=&scope=blobs&search=bug+error+50%2A&snippets=) |
-| `\` | Escape | [`\*md`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=%5C*md&group_id=9970&project_id=278964) |
-| `#` | Issue ID | [`#23456`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=%2323456&group_id=9970&project_id=278964) |
-| `!` | Merge request ID | [`!23456`](https://gitlab.com/search?snippets=&scope=merge_requests&repository_ref=&search=%2123456&group_id=9970&project_id=278964) |
+<!-- Remember to also update the tables in `doc/user/search/advanced_search.md` -->
+
+| Syntax | Description | Example |
+|---------------------|------------------|---------|
+| `"` | Exact search | [`"gem sidekiq"`](https://gitlab.com/search?group_id=9970&project_id=278964&scope=blobs&search=%22gem+sidekiq%22) |
+| `~` | Fuzzy search | [`J~ Doe`](https://gitlab.com/search?scope=users&search=j%7E+doe) |
+| <code>|</code> | Or | [<code>display | banner</code>](https://gitlab.com/search?group_id=9970&project_id=278964&scope=blobs&search=display+%7C+banner) |
+| `+` | And | [`display +banner`](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=&scope=blobs&search=display+%2Bbanner&snippets=) |
+| `-` | Exclude | [`display -banner`](https://gitlab.com/search?group_id=9970&project_id=278964&scope=blobs&search=display+-banner) |
+| `*` | Partial | [`bug error 50*`](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=&scope=blobs&search=bug+error+50%2A&snippets=) |
+| `\` | Escape | [`\*md`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=%5C*md&group_id=9970&project_id=278964) |
+| `#` | Issue ID | [`#23456`](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=%2323456&group_id=9970&project_id=278964) |
+| `!` | Merge request ID | [`!23456`](https://gitlab.com/search?snippets=&scope=merge_requests&repository_ref=&search=%2123456&group_id=9970&project_id=278964) |
## Code search
-| Syntax | Description | Example |
-|--------------|---------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `filename:` | Filename | [`filename:*spec.rb`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=filename%3A*spec.rb&group_id=9970&project_id=278964) |
-| `path:` | Repository location | [`path:spec/workers/`](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=&scope=blobs&search=path%3Aspec%2Fworkers&snippets=) |
-| `extension:` | File extension without `.` | [`extension:js`](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=&scope=blobs&search=extension%3Ajs&snippets=) |
-| `blob:` | Git object ID | [`blob:998707*`](https://gitlab.com/search?snippets=false&scope=blobs&repository_ref=&search=blob%3A998707*&group_id=9970) |
-
-`extension:` and `blob:` return exact matches only.
+| Syntax | Description | Example |
+|--------------|-------------------------------------------------|---------|
+| `filename:` | Filename | [`filename:*spec.rb`](https://gitlab.com/search?snippets=&scope=blobs&repository_ref=&search=filename%3A*spec.rb&group_id=9970&project_id=278964) |
+| `path:` | Repository location (full or partial matches) | [`path:spec/workers/`](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=&scope=blobs&search=path%3Aspec%2Fworkers&snippets=) |
+| `extension:` | File extension without `.` (exact matches only) | [`extension:js`](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=&scope=blobs&search=extension%3Ajs&snippets=) |
+| `blob:` | Git object ID (exact matches only) | [`blob:998707*`](https://gitlab.com/search?snippets=false&scope=blobs&repository_ref=&search=blob%3A998707*&group_id=9970) |
## Examples
-| Query | Description |
-|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------|
-| [`rails -filename:gemfile.lock`](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=&scope=blobs&search=rails+-filename%3Agemfile.lock&snippets=) | Returns `rails` in all files except the `gemfile.lock` file. |
-| [`RSpec.describe Resolvers -*builder`](https://gitlab.com/search?group_id=9970&project_id=278964&scope=blobs&search=RSpec.describe+Resolvers+-*builder) | Returns `RSpec.describe Resolvers` that does not start with `builder`. |
-| [<code>bug | (display +banner)</code>](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=bug+%7C+%28display+%2Bbanner%29&group_id=9970&project_id=278964) | Returns `bug` or both `display` and `banner`. |
-| [<code>helper -extension:yml -extension:js</code>](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=&scope=blobs&search=helper+-extension%3Ayml+-extension%3Ajs&snippets=) | Returns `helper` in all files except files with a `.yml` or `.js` extension. |
+<!-- markdownlint-disable MD044 -->
+
+| Query | Description |
+|----------------------------------------------------|-------------|
+| [`rails -filename:gemfile.lock`](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=&scope=blobs&search=rails+-filename%3Agemfile.lock&snippets=) | Returns `rails` in all files except the `gemfile.lock` file. |
+| [`RSpec.describe Resolvers -*builder`](https://gitlab.com/search?group_id=9970&project_id=278964&scope=blobs&search=RSpec.describe+Resolvers+-*builder) | Returns `RSpec.describe Resolvers` that does not start with `builder`. |
+| [<code>bug | (display +banner)</code>](https://gitlab.com/search?snippets=&scope=issues&repository_ref=&search=bug+%7C+%28display+%2Bbanner%29&group_id=9970&project_id=278964) | Returns `bug` or both `display` and `banner`. |
+| [<code>helper -extension:yml -extension:js</code>](https://gitlab.com/search?group_id=9970&project_id=278964&repository_ref=&scope=blobs&search=helper+-extension%3Ayml+-extension%3Ajs&snippets=) | Returns `helper` in all files except files with a `.yml` or `.js` extension. |
+| [<code>helper path:lib/git</code>](https://gitlab.com/search?group_id=9970&project_id=278964&scope=blobs&search=helper+path%3Alib%2Fgit) | Returns `helper` in all files with a `lib/git*` path (for example, `spec/lib/gitlab`). |
-<!-- markdownlint-enable -->
+<!-- markdownlint-enable MD044 -->
diff --git a/doc/drawers/exact_code_search_syntax.md b/doc/drawers/exact_code_search_syntax.md
index be99331961091..118cf5e654a43 100644
--- a/doc/drawers/exact_code_search_syntax.md
+++ b/doc/drawers/exact_code_search_syntax.md
@@ -7,19 +7,21 @@ source: /doc/user/search/exact_code_search.md
# Syntax options
-| Query | Regular expression mode | Exact match mode |
-| -------------------- | ------------------------------------------------------- | ------------------------------ |
-| `"foo"` | `foo` | `"foo"` |
+<!-- Remember to also update the table in `doc/user/search/exact_code_search.md` -->
+
+| Query | Exact match mode | Regular expression mode |
+| -------------------- | ------------------------------------------------------- | ----------------------- |
+| `"foo"` | `"foo"` | `foo` |
| `foo file:^doc/` | `foo` in directories that start with `/doc` | `foo` in directories that start with `/doc` |
-| `"class foo"` | `class foo` | `"class foo"` |
-| `class foo` | `class` and `foo` | `class foo` |
-| `foo or bar` | `foo` or `bar` | `foo or bar` |
-| `class Foo` | `class` (case insensitive) and `Foo` (case sensitive) | `class Foo` (case insensitive) |
-| `class Foo case:yes` | `class` and `Foo` (both case sensitive) | `class Foo` (case sensitive) |
-| `foo -bar` | `foo` but not `bar` | `foo -bar` |
+| `"class foo"` | `"class foo"` | `class foo` |
+| `class foo` | `class foo` | `class` and `foo` |
+| `foo or bar` | `foo or bar` | `foo` or `bar` |
+| `class Foo` | `class Foo` (case insensitive) | `class` (case insensitive) and `Foo` (case sensitive) |
+| `class Foo case:yes` | `class Foo` (case sensitive) | `class` and `Foo` (both case sensitive) |
+| `foo -bar` | `foo -bar` | `foo` but not `bar` |
| `foo file:js` | `foo` in files with names that contain `js` | `foo` in files with names that contain `js` |
| `foo -file:test` | `foo` in files with names that do not contain `test` | `foo` in files with names that do not contain `test` |
-| `foo lang:ruby` | `foo` in Ruby source code | `foo` in Ruby source code |
+| `foo lang:ruby` | `foo` in Ruby source code | `foo` in Ruby source code |
| `foo file:\.js$` | `foo` in files with names that end with `.js` | `foo` in files with names that end with `.js` |
-| `foo.*bar` | `foo.*bar` (regular expression) | None |
+| `foo.*bar` | None | `foo.*bar` (regular expression) |
| `sym:foo` | `foo` in symbols like class, method, and variable names | `foo` in symbols like class, method, and variable names |
diff --git a/doc/integration/exact_code_search/zoekt.md b/doc/integration/exact_code_search/zoekt.md
index 783afc75d446a..f7429b5957117 100644
--- a/doc/integration/exact_code_search/zoekt.md
+++ b/doc/integration/exact_code_search/zoekt.md
@@ -23,7 +23,7 @@ Zoekt is an open-source search engine designed specifically to search for code.
With this integration, you can use [exact code search](../../user/search/exact_code_search.md)
instead of [advanced search](../../user/search/advanced_search.md) to search for code in GitLab.
-You can use regular expression and exact match modes to search for code in a group or repository.
+You can use exact match and regular expression modes to search for code in a group or repository.
## Install Zoekt
@@ -79,7 +79,8 @@ Prerequisites:
- You must have administrator access to the instance.
-You can index both existing and new root namespaces automatically. To index all root namespaces automatically:
+You can index both existing and new root namespaces automatically.
+To index all root namespaces automatically:
1. On the left sidebar, at the bottom, select **Admin**.
1. Select **Settings > Search**.
@@ -109,22 +110,19 @@ To pause indexing for [exact code search](../../user/search/exact_code_search.md
When you pause indexing for exact code search, all changes in your repository are queued.
To resume indexing, clear the **Pause indexing for exact code search** checkbox.
-## Control indexing concurrency
+## Set concurrent indexing tasks
Prerequisites:
- You must have administrator access to the instance.
-You can set the number of concurrent indexing tasks
-that can be run on a Zoekt node relative to its CPU capacity.
+You can set the number of concurrent indexing tasks for a Zoekt node relative to its CPU capacity.
-A higher ratio allows more tasks to run concurrently, potentially
-improving indexing throughput at the cost of increased CPU usage.
-The default value is `1.0`, meaning one task per CPU core.
-
-You can adjust this value based on your Zoekt node's performance
-characteristics and workload.
+A higher multiplier means more tasks can run concurrently, which would
+improve indexing throughput at the cost of increased CPU usage.
+The default value is `1.0` (one task per CPU core).
+You can adjust this value based on the node's performance and workload.
To set the number of concurrent indexing tasks:
1. On the left sidebar, at the bottom, select **Admin**.
@@ -132,8 +130,9 @@ To set the number of concurrent indexing tasks:
1. Expand **Exact code search configuration**.
1. In the **Indexing CPU to tasks multiplier** text box, enter a value.
- For example, if a Zoekt node has `4` CPU cores and the ratio is set to `1.5`, the
- number of concurrent tasks for a node is going to be `4 * 1.5`, which is `6`.
+ For example, if a Zoekt node has `4` CPU cores and the multiplier is `1.5`,
+ the number of concurrent tasks for the node is `6`.
+
1. Select **Save changes**.
## Troubleshooting
diff --git a/doc/user/search/advanced_search.md b/doc/user/search/advanced_search.md
index 6a89eb84957d2..d42edb6242b36 100644
--- a/doc/user/search/advanced_search.md
+++ b/doc/user/search/advanced_search.md
@@ -41,6 +41,8 @@ You can use advanced search in:
## Syntax
+<!-- Remember to also update the tables in `doc/drawers/advanced_search_syntax.md` -->
+
> - Refining user search [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/388409) in GitLab 15.10.
Advanced search uses [`simple_query_string`](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-simple-query-string-query.html),
diff --git a/doc/user/search/exact_code_search.md b/doc/user/search/exact_code_search.md
index 64c98b8b3868e..9b49e8c66c291 100644
--- a/doc/user/search/exact_code_search.md
+++ b/doc/user/search/exact_code_search.md
@@ -19,7 +19,7 @@ WARNING:
This feature is in [beta](../../policy/experiment-beta-support.md#beta) and subject to change without notice.
For more information, see [epic 9404](https://gitlab.com/groups/gitlab-org/-/epics/9404).
-With exact code search, you can use regular expression and exact match modes
+With exact code search, you can use exact match and regular expression modes
to search for code in all GitLab or in a specific project.
Exact code search is powered by [Zoekt](https://github.com/sourcegraph/zoekt)
@@ -70,8 +70,8 @@ When this feature is enabled for instances with more than 20,000 projects, your
GitLab has two search modes:
-- **Regular expression mode:** supports regular and boolean expressions.
- **Exact match mode:** returns results that exactly match the query.
+- **Regular expression mode:** supports regular and boolean expressions.
The exact match mode is used by default.
To switch to the regular expression mode, to the right of the search box,
@@ -79,23 +79,25 @@ select **Use regular expression** (**{regular-expression}**).
### Syntax
-This table shows some example queries for regular expression and exact match modes.
+<!-- Remember to also update the table in `doc/drawers/exact_code_search_syntax.md` -->
+
+This table shows some example queries for exact match and regular expression modes.
-| Query | Regular expression mode | Exact match mode |
-| -------------------- | ------------------------------------------------------- | ------------------------------ |
-| `"foo"` | `foo` | `"foo"` |
+| Query | Exact match mode | Regular expression mode |
+| -------------------- | ------------------------------------------------------- | ----------------------- |
+| `"foo"` | `"foo"` | `foo` |
| `foo file:^doc/` | `foo` in directories that start with `/doc` | `foo` in directories that start with `/doc` |
-| `"class foo"` | `class foo` | `"class foo"` |
-| `class foo` | `class` and `foo` | `class foo` |
-| `foo or bar` | `foo` or `bar` | `foo or bar` |
-| `class Foo` | `class` (case insensitive) and `Foo` (case sensitive) | `class Foo` (case insensitive) |
-| `class Foo case:yes` | `class` and `Foo` (both case sensitive) | `class Foo` (case sensitive) |
-| `foo -bar` | `foo` but not `bar` | `foo -bar` |
+| `"class foo"` | `"class foo"` | `class foo` |
+| `class foo` | `class foo` | `class` and `foo` |
+| `foo or bar` | `foo or bar` | `foo` or `bar` |
+| `class Foo` | `class Foo` (case insensitive) | `class` (case insensitive) and `Foo` (case sensitive) |
+| `class Foo case:yes` | `class Foo` (case sensitive) | `class` and `Foo` (both case sensitive) |
+| `foo -bar` | `foo -bar` | `foo` but not `bar` |
| `foo file:js` | `foo` in files with names that contain `js` | `foo` in files with names that contain `js` |
| `foo -file:test` | `foo` in files with names that do not contain `test` | `foo` in files with names that do not contain `test` |
-| `foo lang:ruby` | `foo` in Ruby source code | `foo` in Ruby source code |
+| `foo lang:ruby` | `foo` in Ruby source code | `foo` in Ruby source code |
| `foo file:\.js$` | `foo` in files with names that end with `.js` | `foo` in files with names that end with `.js` |
-| `foo.*bar` | `foo.*bar` (regular expression) | None |
+| `foo.*bar` | None | `foo.*bar` (regular expression) |
| `sym:foo` | `foo` in symbols like class, method, and variable names | `foo` in symbols like class, method, and variable names |
## Known issues
diff --git a/doc/user/search/index.md b/doc/user/search/index.md
index 5fd5376e2ce2f..953f5c2a89a45 100644
--- a/doc/user/search/index.md
+++ b/doc/user/search/index.md
@@ -15,7 +15,7 @@ and [**exact code search**](exact_code_search.md).
For code search, GitLab uses these types in this order:
-- **Exact code search:** where you can use regular expression and exact match modes.
+- **Exact code search:** where you can use exact match and regular expression modes.
- **Advanced search:** when exact code search is not available.
- **Basic search:** when exact code search and advanced search are not available
or when you search against a non-default branch.
--
GitLab