Dagger TypeScript SDK FileSearchOpts 类型全解析用 File.search 与 Directory.search 实现仓库级内容检索【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger导读FileSearchOpts是 Dagger TypeScript SDKdagger.io/dagger版本 0.19为File.search()与Directory.search()方法提供的可选参数类型用于定义在 Dagger 引擎中检索文件内容的匹配规则。本文以该类型别名文档为主体结合仓库中 core/search.go 的核心实现与 core/integration/file_test.go 的集成测试逐字段讲解每个选项的语义、与底层 ripgrep 参数的映射关系并给出可直接复制的 TypeScript 实战示例。读完本文你将掌握如何用 Dagger 在任意文件或目录上执行字面量检索、正则检索、多行匹配、忽略隐藏文件/被忽略文件等能力并能在自己的 Dagger 模块中正确使用这一 API。类型别名概览在 TypeScript SDK 中FileSearchOpts定义于 sdk/typescript/src/api/client.gen.ts生成文件对应的 API 参考文档即 type-aliases/FileSearchOpts.md其完整形态如下export type FileSearchOpts { /** * Interpret the pattern as a literal string instead of a regular expression. */ literal?: boolean /** * Enable searching across multiple lines. */ multiline?: boolean /** * Allow the . pattern to match newlines in multiline mode. */ dotall?: boolean /** * Enable case-insensitive matching. */ insensitive?: boolean /** * Honor .gitignore, .ignore, and .rgignore files. */ skipIgnored?: boolean /** * Skip hidden files (files starting with .). */ skipHidden?: boolean /** * Only return matching files, not lines and content */ filesOnly?: boolean /** * Limit the number of results to return */ limit?: number paths?: string[] globs?: string[] }所有字段均为可选调用方按需传入即可。该类型被File.search()方法签名直接引用见 sdk/typescript/src/api/client.gen.ts 中search async (pattern: string, opts?: FileSearchOpts): PromiseSearchResult[]的定义同时也被Directory.search()复用。属性详解与底层映射FileSearchOpts的 10 个属性虽然定义在 TypeScript 层但每个布尔选项都能在 Dagger 引擎核心的SearchOpts结构体及其RipgrepArgs()方法core/search.go中找到一一对应的 ripgrep 命令行参数。理解这层映射是掌握该 API 行为的关键。literal字面量匹配类型boolean可选语义将pattern当作普通字符串而非正则表达式进行匹配。引擎映射--fixed-strings说明开启后不再解析正则元字符。引擎内部在实现WithReplaced文本替换时便强制使用Literal: true并在模式含换行时自动附带Multiline: true见 core/file.go 的WithReplaced实现可见字面量匹配是文本级操作的安全选择。multiline跨行匹配类型boolean可选语义允许模式跨越多行进行匹配。引擎映射--multiline说明对应 ripgrep 的多行模式-U启用后匹配不再局限于单行文本。集成测试中即用多行模式检索: Alice\n\tage这类跨行模式。dotall点号匹配换行类型boolean可选语义在多行模式下允许正则中的.匹配换行符。引擎映射--multiline-dotall说明该选项只在multiline开启时才有意义。例如用: .*\n\sage这样的模式跨行匹配变量声明时配合dotall可让.*吞掉换行。insensitive忽略大小写类型boolean可选语义启用大小写不敏感匹配。引擎映射--ignore-case说明集成测试case insensitive searchcore/integration/file_test.go验证了在内容为Hello\nhello\nHELLO\nHeLLo的文件中搜索hello并传入Insensitive: true可命中全部 4 行。skipIgnored跳过被忽略文件类型boolean可选语义尊重.gitignore、.ignore与.rgignore文件不搜索其中列出的文件。引擎映射反向逻辑——当skipIgnored为false时引擎主动追加--no-ignore见RipgrepArgs()中if !opts.SkipIgnored { args append(args, --no-ignore) }。说明这是一个容易误解的默认值Dagger 的搜索默认会搜索被 git 忽略的文件只有显式设置skipIgnored: true才恢复 ripgrep 尊重 ignore 文件的默认行为。skipHidden跳过隐藏文件类型boolean可选语义跳过以.开头的隐藏文件。引擎映射反向逻辑——当skipHidden为false时引擎主动追加--hidden即默认会搜索隐藏文件设置skipHidden: true后不再追加该参数隐藏文件被跳过。filesOnly仅返回文件名类型boolean可选语义只返回命中的文件不返回匹配行与内容。引擎映射--files-with-matches未开启时使用--json并解析完整的匹配明细。说明引擎在filesOnly模式下按行解析输出构造仅含FilePath的SearchResult见 core/search.go 的parseRgOutput适合“哪些文件包含该模式”这类清单场景。limit限制结果数量类型number可选语义限制返回的结果数量。说明与其它选项不同limit没有对应的 ripgrep 标志。源码注释明确指出「opts.Limit 在解析结果时处理没有只限制总数而不限制单文件结果的标志」因此引擎在逐条解析 JSON 输出时一旦累计结果数达到limit即提前中断见parseRgOutput中if opts.Limit ! nil len(results) *opts.Limit { break }。paths 与 globs限定搜索范围类型string[]可选语义paths限定搜索的具体路径globs按 glob 规则过滤参与搜索的文件。实现这两个字段主要由Directory.search()使用。在 core/directory.go 的Directory.Search实现中每个glob被追加为--globglob每个path会先被校验并规范化filepath.Clean且拒绝任何会逃逸出目录的路径如../再以--分隔符追加为显式搜索目标。安全说明路径参数在引擎侧做了防目录穿越校验非法的越界路径会直接返回path cannot escape directory错误。注意File.search()的实现只针对单个文件本身rgArgs append(rgArgs, --, filepath.Base(filePath))paths/globs对单文件搜索不生效主要面向目录级搜索。使用示例在单个文件中检索import { Client, connect } from dagger.io/dagger connect(async (client: Client) { const file client .host() .directory(.) .file(README.md) // 正则检索忽略大小写 const results await file.search(install, { insensitive: true, limit: 10, }) for (const r of results) { console.log( ${r.filePath}:${r.lineNumber}: ${(await r.matchedLines).trim()}, ) } })目录级检索只列文件名const dir client.host().directory(./src) // 只看哪些 Go 文件包含 TODO跳过隐藏文件与 git 忽略的文件 const files await dir.search(TODO, { filesOnly: true, skipHidden: true, skipIgnored: true, globs: [*.go], })多行 点号匹配// 匹配跨行的变量声明模式 const results await file.search(: .*\n\\sage, { multiline: true, dotall: true, })字面量检索// 把包含正则元字符的字符串当作普通文本搜索 const results await file.search(a[i].txt, { literal: true })返回结构SearchResultFileSearchOpts只负责描述「怎么搜」而「搜到什么」由SearchResult描述。其引擎侧定义core/search.go包含以下字段字段含义FilePath命中的文件路径LineNumber首个匹配行号1 起始AbsoluteOffset该行在文件内的字节偏移MatchedLines命中的行内容Submatches子匹配数组Text、Start、End偏移基于匹配行文本引擎以 JSON 流方式解析 ripgrep 输出会跳过非 UTF-8 的内容并记录告警当 ripgrep 以退出码 1 退出时表示无匹配此时返回空结果而非报错见RunRipgrep中对ExitCode() 1的处理。集成测试佐证core/integration/file_test.go 中的FileSuite.TestSearch覆盖了该 API 的主要能力是理解FileSearchOpts行为的最佳参照literal search对内容含 3 处World的文本文件直接file.Search(ctx, World)断言返回 3 条结果及其行号1、3、4、匹配文本与子匹配结构regex search用\w :检索 Go 源码中的变量赋值验证AbsoluteOffset非负、每个结果至少一个子匹配并精确断言code.go:6: name : Alice等命中multiline search与case insensitive search分别验证跨行模式与Insensitive: true下大小写不敏感命中 4 行Hello/hello/HELLO/HeLLo。Go SDK 生成的对应结构体可见于 core/integration/testdata/modules/go/defaults/foobar/internal/dagger/dagger.gen.goFileSearchOpts结构体与File.Search生成方法字段与 TypeScript 版本完全对应方便跨语言对齐。使用注意事项正则语法search的pattern使用 Rust regex 语法文档明确要求对字面量.、[、]、{、}、|用反斜杠转义不确定时可改用literal: true。默认会搜隐藏与被忽略文件Dagger 的默认行为与 ripgrep 不同——除非显式设置skipHidden/skipIgnored隐藏文件与被.gitignore忽略的文件都会被纳入搜索范围。dotall依赖multiline单独开启dotall无效需配合multiline: true使用。paths/globs主要用于目录搜索对File.search不产生实际效果目录搜索的paths受防目录穿越校验约束。limit是结果总数上限在多文件目录搜索中它限制返回的SearchResult总数而非每个文件的命中数。无匹配不是错误搜索无结果时返回空数组调用方无需做错误分支处理。【免费下载链接】daggerAutomation engine to build, test and ship any codebase. Runs locally, in CI, or directly in the cloud项目地址: https://gitcode.com/GitHub_Trending/da/dagger创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考