From 757fb1927a4915cfe18d43fd3e23190762ff0f54 Mon Sep 17 00:00:00 2001
From: silverwind <2021+silverwind@noreply.gitea.com>
Date: Fri, 13 Nov 2026 18:45:17 +0000
Subject: [PATCH] Document code search and its query syntax (#615)

Documents https://github.com/go-gitea/gitea/pull/39403: a new user page for code search with the query syntax, results and API endpoints, and an update to the repository indexer page saying that `git grep` search needs Git with PCRE.

_Written by Claude._

Reviewed-on: https://gitea.com/gitea/docs/pulls/615
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: silverwind <2021+silverwind@noreply.gitea.com>
---
 docs/administration/repo-indexer.md |  7 ++---
 docs/usage/code-search.md           | 42 +++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+), 3 deletions(-)
 create mode 100644 docs/usage/code-search.md

diff --git a/docs/administration/repo-indexer.md b/docs/administration/repo-indexer.md
index acc0af02..346c6100 100644
--- a/docs/administration/repo-indexer.md
+++ b/docs/administration/repo-indexer.md
@@ -10,9 +10,10 @@ aliases:
 
 ## Builtin repository code search without indexer
 
-Users could do repository-level code search without setting up a repository indexer.
-The builtin code search is based on the `git grep` command, which is fast and efficient for small repositories.
-Better code search support could be achieved by setting up the repository indexer.
+Users can search the code of a single repository without setting up a repository indexer.
+This search uses `git grep`, which is fast for small repositories and requires Git built with PCRE support, as most distributions provide.
+Searching across repositories requires the repository indexer.
+See [Code Search](../usage/code-search.md) for the query syntax.
 
 ## Setting up the repository indexer
 
diff --git a/docs/usage/code-search.md b/docs/usage/code-search.md
new file mode 100644
index 00000000..1aaf1d36
--- /dev/null
+++ b/docs/usage/code-search.md
@@ -0,0 +1,42 @@
+---
+date: "2026-10-29T00:00:00+00:00"
+slug: "code-search"
+sidebar_position: 50
+---
+
+# Code Search
+
+Search code in a single repository with the search box on the repository's code tab. To search across repositories, use the **Code** tab on the explore page or on a user or organization profile. Searching across repositories requires the [repository indexer](../administration/repo-indexer.md).
+
+## Query syntax
+
+A file is found when every term matches its content or its path. Matching ignores case and also finds terms inside longer words, so `port` matches `import`.
+
+| Syntax | Example | Finds files that |
+| --- | --- | --- |
+| `term` | `getUser` | contain `getUser` |
+| `term term` | `user cache` | contain both `user` and `cache` |
+| `"phrase"` | `"func main()"` | contain the exact text, including spaces |
+| `/regexp/` | `/get\w+User/` | have a line matching the regular expression |
+| `path:DIR` | `path:src/utils` | are inside the `src/utils` directory |
+| `language:NAME` | `language:go` | are written in Go |
+| `repo:OWNER/NAME` | `repo:gitea/tea` | are in the `gitea/tea` repository |
+| `user:NAME`, `org:NAME` | `org:gitea` | are in a repository owned by `gitea` |
+
+- `repo:`, `user:` and `org:` only work when searching across repositories. Repeat them to search several, for example `repo:gitea/tea repo:gitea/act`.
+- Regular expressions only work when the repository indexer is not enabled. They match one line at a time, so use `\s` for spaces, as a space separates terms.
+- `language:` only works with the repository indexer.
+- `AND`, `OR`, `NOT`, negated qualifiers like `-path:`, and qualifiers like `content:` or `extension:` are not supported and show an error.
+
+## Results
+
+Each file shows up to 10 snippets with the matches highlighted. Binary files are only found by their path.
+
+Without the repository indexer, a search stops after 50 files and shows a notice. Narrow the query with more terms or `path:` to see the rest.
+
+## API
+
+- `GET /api/v1/repos/{owner}/{repo}/code/search?q=...` searches one repository. Set `ref` to search a branch, tag or commit other than the default branch. It always supports regular expressions, but not `language:`.
+- `GET /api/v1/search/code?q=...` searches the default branches of all repositories you can read. It requires the repository indexer and does not support regular expressions.
+
+Both return results in GitHub's format, including `text_matches` with the match positions. Results can be paged up to the 1000th file.