search_content
Find which files mention a topic anywhere in their full content, including inactive #ifdef branches and file-scope comments. Returns file-level results with match lines and highlighted snippets.
Instructions
Find patterns in FULL file content — the whole file, not only the text that belongs to a definition.
Searches ifdef-filtered file text — only code that actually compiles
for the current build configuration. Inactive #ifdef branches are
replaced with blank lines (preserving original line numbers). A pattern
that lives only in a dead branch therefore gives no result, and that
empty answer is the correct one: the code does not compile.
Covers the text that belongs to no definition, which is what
search_bodies cannot see: #include, #define, #ifdef,
extern "C", and a comment or declaration at file scope. It covers
the text of definitions too. To find a symbol by NAME (modem init,
interrupt handler), use search_code.
Not a fallback of search_bodies — its complement. The two
answer different questions and reach different text:
search_bodiesanswers WHICH DEFINITION holds the pattern, and takes the query literally (no wildcard, space = AND).search_contentanswers WHICH FILES the topic touches, and widens the query: every term gets a trailing*and the terms are OR-joined. The wider query reaches text the literal one misses — measured on one project,SELF_TESTfound 6 files here and the same word found 5 throughsearch_bodies, the extra file holding the commentSelf tester.
For the footprint of one feature, run both.
Results are file-level — one entry per matching file, with
match_lines for the lines that hold a query term.
project_only=True filters to is_project = 1 files; the default
False includes the vendor SDK files.
When files_fts is missing (legacy index), falls back to LIKE
search on files.content — results include _fallback: "like"
and no snippet highlighting. Run fw-context index to upgrade.
Read-only: yes. Requires the FTS5 index with file content. May
auto-reindex stale files (non-blocking) — see search_code.
Args:
query: FTS5 search terms. 1-3 words. Bare multi-word queries are
OR-joined (prefix-wildcarded). Prefer single-word queries.
E.g. 'InterruptIn', 'extern C', '#define'.
project_root: Project root. Auto-detected if omitted.
project: Project name or project_id — call list_projects to get them. Use
it to ask about a project that is not the project of the current
directory. It is an alternative to project_root, which takes a root
path. Give one of the two, not both.
limit: Maximum results of one page (default 20, max 100).
offset: Skip this many results. Reads the next page of a topic
that many files touch; the page notice names the offset to use.
project_only: When True, filter to project code only (files with is_project = 1).
variant: Build variant (multi-build project). Omit to use
default_variant. One query answers for ONE build.
image: Sysbuild image within the variant. Required when the
variant holds several: each image is a separate program.
Returns:
list of dicts. The page notice leads the answer — total,
offset, shown, more — and each that follows holds:
file, language, mtime, _match_snippet (highlighted excerpt around
the match).
Also, when it carries an answer:
* ``match_lines`` (list[int]) — line numbers of the lines that hold
a query term, up to 20. They are the line numbers of the file
itself: an inactive ``#ifdef`` branch is a blank line, thus the
count never shifts. Cite ``file:line`` from here.
The field is absent when FTS5 matched a variant of the token that
the term is not a substring of — ``SELF_TEST`` matches the file
that writes ``Self tester``, and no line holds ``self_test``.
Read ``_match_snippet`` in that case.
No match gives ``[]``. A dict with ``error`` means the query
failed. A stale index prepends a dict with ``warning`` + ``hint``,
and so does a query that FTS5 refuses to parse — the answer then
comes from the LIKE path and carries ``_fallback: "like"``.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| image | No | Sysbuild image within the variant. Required when the variant holds several: each image is a separate program. | |
| limit | No | Maximum results of one page (default 20, max 100). | |
| query | Yes | FTS5 search terms for full file content. 1-3 words. E.g. 'InterruptIn', 'extern C'. Bare multi-word = OR-joined. | |
| offset | No | Skip this many results. Reads the next page of a topic that many files touch. | |
| project | No | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. | |
| variant | No | Build variant (multi-build project). Omit to use default_variant. One query answers for ONE build. | |
| project_only | No | Exclude vendor SDK code. When True, only application code. Default False. | |
| project_root | No | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |