Dagger TypeScript SDK DirectorySearchOpts 完全指南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/daggerDagger 的Directory.search()方法让你在容器化构建的目录中用正则表达式或字面量文本进行内容检索并返回带行号、偏移量与子匹配位置的结构化结果。本文以 TypeScript SDK 参考文档中的DirectorySearchOpts类型别名docs/versioned_docs/version-0.21/reference/typescript/api/client.gen/type-aliases/DirectorySearchOpts.md为骨架结合底层实现与集成测试逐一讲解全部 11 个选项的语义、默认值、底层 ripgrep 映射以及实战用法。读完本文你将能精准控制 Dagger 目录搜索的行为边界写出高效、可预测的检索代码。DirectorySearchOpts 是什么DirectorySearchOpts是 Dagger TypeScript SDK 为Directory.search(opts?)方法定义的可选参数对象类型其定义位于 sdk/typescript/src/api/client.gen.ts由代码生成器从 Dagger GraphQL API 自动生成属于client.gen这一层「自动生成客户端」的一部分。在类型层面它是这样一个结构export type DirectorySearchOpts { paths?: string[] globs?: string[] pattern: string // 唯一必填项 literal?: boolean multiline?: boolean dotall?: boolean insensitive?: boolean skipIgnored?: boolean skipHidden?: boolean filesOnly?: boolean limit?: number }其中只有pattern是必填字段其余均为可选。从 GraphQL 语义看这些选项对应Directory.search的一个参数对象对应的search方法在 SDK 中签名如下sdk/typescript/src/api/client.gen.tssearch async (opts?: DirectorySearchOpts): PromiseSearchResult[] { ... }调用后返回SearchResult[]每个SearchResult包含filePath、lineNumber、absoluteOffset、matchedLines与submatches字段对应的服务端对象定义在 core/search.go。必填参数 pattern要匹配的文本pattern是唯一必填选项类型为string表示要匹配的文本。它的语义受literal选项影响默认情况下pattern被当作正则表达式解释当literal: true时被当作字面量字符串不进行正则解析。在底层实现中pattern 最终以--regexppattern的形式传给 ripgrepcore/search.go。值得注意的是Dagger 使用的正则语法是Rust regex 语法——在 GraphQL Schema 中明确注明「Uses Rust regex syntax; escape literal ., [, ], {, }, | with backslashes」core/schema/directory.go。也就是说想匹配字面量的.、[、]、{、}、|等特殊字符时需要用反斜杠转义例如pattern: foo\\.barRust regex 不支持回溯backreference等 PCRE 特性编写复杂正则时需注意这一点更稳妥的做法是使用literal: true直接按字面量匹配例如在WithReplaced的底层实现中替换前的查找就强制使用Literal: truecore/file.go。控制匹配范围paths 与 globs这两个选项负责限定「在哪些文件里搜」是控制搜索结果规模的第一道闸门。paths目录或文件路径列表paths?: string[]用于指定要搜索的目录或文件路径与「在哪个目录对象上调用 search」共同决定搜索范围。在服务端实现中这些路径会经过严格的路径穿越防护处理core/directory.go绝对路径会被转换为相对于当前目录的路径去掉开头的/路径会被filepath.Clean规范化清理../、./等片段规范化后若路径试图逃出当前目录!filepath.IsLocal会直接报错path cannot escape directory。安全校验通过后各路径经containerdfs.RootPath解析为实际挂载根下的相对路径追加在--之后传给 ripgrepcore/directory.go从而把搜索精确限制在这些文件或子目录内。globsglob 模式列表globs?: string[]用于按文件名模式过滤例如*.md只匹配 Markdown 文件。每个 glob 会被转换为 ripgrep 的--globglob参数core/directory.go支持*、?、**等通配符。需要注意globs 与 paths 是叠加关系先通过 paths 限定搜索起点再用 globs 过滤具体文件类型glob 语义遵循 ripgrep 的规则基于 gitignore 风格例如!*.min.js可用于排除。集成测试中有专门的 globs 用例core/integration/directory_test.go在同时包含main.go、test.go、README.md的目录里通过 globs 精确圈定要搜索的文件集。正则行为控制literal、multiline 与 dotall这三个选项直接映射到 ripgrep 的匹配引擎行为理解它们的组合关系是写出正确搜索的关键。literal字面量匹配literal?: boolean默认false。当为true时pattern按字面字符串匹配底层映射为 ripgrep 的--fixed-stringscore/search.go。典型场景搜索代码中恰好含正则元字符的文本如a[i]、foo{2}或pattern来自用户输入、不可控时用字面量模式既安全又符合直觉。multiline跨行匹配multiline?: boolean默认false。开启后允许正则跨越多行进行匹配底层映射为--multilinecore/search.go。典型用例是在多行代码结构中定位目标例如集成测试中搜索: Alice\n\tage这一跨行赋值序列core/integration/directory_test.go。dotall点号匹配换行符dotall?: boolean默认false。它仅在 multiline 模式下有意义开启后允许正则中的.匹配换行符底层映射为--multiline-dotallcore/search.go。组合示例multiline: true, dotall: true时.*可以跨越任意字符包括换行进行贪婪匹配例如测试中的: .*\n\sage模式core/integration/directory_test.go。三者关系总结如下表选项默认值底层 ripgrep 参数作用literalfalse--fixed-stringspattern 按字面量匹配multilinefalse--multiline允许跨行匹配dotallfalse--multiline-dotallmultiline 下.可匹配换行匹配策略insensitive、filesOnly 与 limitinsensitive大小写不敏感insensitive?: boolean默认false。开启后忽略大小写匹配底层映射为--ignore-casecore/search.go。集成测试验证对内容为Hello\nhello\nHELLO的文件执行search(hello, { insensitive: true })三条记录全部命中core/integration/directory_test.go。filesOnly只返回文件名filesOnly?: boolean默认false。开启后只返回命中的文件路径不返回行号、行内容与子匹配底层映射为--files-with-matchescore/search.go并切换到「逐行读路径」的结果解析分支core/search.go每个结果只有filePath有意义。适合「判断某个文件中是否存在目标文本」的快速探测场景。集成测试确认匹配World时返回file1.txt与subdir/file3.txt而matchedLines为空core/integration/directory_test.go。limit结果数量上限limit?: number默认不限。限制返回结果的最大条数。注意其实现方式很特别它不通过 ripgrep 参数实现——因为 rg 只提供按文件限制结果数的参数无法直接限制总结果数——而是在解析输出流的过程中当已收集的结果数达到limit时立即停止解析core/search.go。这意味着限制在「结果解析层」生效底层仍会跑完整个搜索。集成测试验证Limit: 3时只返回 3 条结果core/integration/directory_test.go。文件过滤skipHidden 与 skipIgnoredskipHidden跳过隐藏文件skipHidden?: boolean默认false。为true时跳过以.开头的隐藏文件如.env、.gitignore自身、.github目录。其映射逻辑与直觉相反但很实用只有当skipHidden为false时才会追加--hiddencore/search.go。这是因为 ripgrep 默认会跳过隐藏文件而 Dagger 默认要「连隐藏文件一起搜」于是反过来用--hidden关闭 rg 的默认隐藏行为。skipIgnored尊重忽略规则skipIgnored?: boolean默认false。为true时尊重.gitignore、.ignore、.rgignore等忽略规则文件为false默认时忽略这些规则搜索全部文件。映射逻辑与 skipHidden 对称默认追加--no-ignorecore/search.go。集成测试用三种场景验证了这一行为core/integration/directory_test.go默认skipIgnored: falsetracked.txt、ignored.log、build/output.bin全部命中skipIgnored: true且存在.gitignore仅tracked.txt命中skipIgnored: true且存在.rgignore同样仅tracked.txt命中。底层实现每个选项如何变成 ripgrep 参数DirectorySearchOpts在服务端对应core.SearchOpts结构体core/search.go两者字段一一对应。所有布尔选项的默认值都是falselimit为可空指针。将 TypeScript 选项翻译为 GraphQL 参数后服务端通过RipgrepArgs()方法完成到 ripgrep CLI 参数的最终映射core/search.go完整对应关系如下选项映射逻辑literaltrue→--fixed-stringsmultilinetrue→--multilinedotalltrue→--multiline-dotallinsensitivetrue→--ignore-caseskipIgnoredfalse默认→--no-ignoreskipHiddenfalse默认→--hiddenfilesOnlytrue→--files-with-matchesfalse→--jsonlimit不传参在结果解析时截断pattern恒为--regexppattern固定行为恒追加--no-follow禁止跟随符号链接core/search.go搜索执行流程是Directory.Search挂载目录快照 → 解析出实际根路径 → 组装rg命令exec.Command(rg, rgArgs...)工作目录设为解析后的目录→ 调用RunRipgrep解析 JSON 流输出core/directory.go。结果解析时逐条读取 ripgrep 的 JSON 输出组装SearchResult文件路径、行号、字节偏移、命中的行文本与子匹配区间并对非 UTF-8 内容做跳过处理core/search.go。实战示例组合使用各选项以下是一个综合使用DirectorySearchOpts的 TypeScript 示例演示如何在一个源码目录中做「大小写不敏感、排除隐藏文件与忽略规则、限定 Go 文件、只返回文件名、最多 20 条」的搜索import { connect } from dagger.io/dagger await connect(async (client) { const src client.host().directory(./repo) const results await src.search(TODO|FIXME, { paths: [src], // 只搜 src 子目录 globs: [*.go], // 只搜 Go 文件 insensitive: true, // 忽略大小写 skipHidden: true, // 跳过隐藏文件 skipIgnored: true, // 尊重 .gitignore 等规则 filesOnly: true, // 只返回文件名 limit: 20, // 最多 20 条结果 }) for (const r of results) { console.log(await r.filePath()) } })如果需要带上下文的完整检索去掉filesOnly即可获得SearchResult上的lineNumber、matchedLines与submatches子匹配的精确文本与起止偏移满足代码检查、文档审计等更细粒度的需求。相关 API 与测试入口类型定义与 search 方法sdk/typescript/src/api/client.gen.ts、sdk/typescript/src/api/client.gen.ts服务端选项与 ripgrep 映射core/search.go目录搜索实现含路径防护core/directory.go文件级搜索File.search复用同一套选项core/file.goGraphQL 层参数声明core/schema/directory.go集成测试filesOnly / limit / multiline / insensitive / skipIgnored / globs 等全场景core/integration/directory_test.go需要说明的是Dagger 还提供了功能相近但选项略有差异的FileSearchOpts与WorkspaceSearchOpts均在 sdk/typescript/src/api/client.gen.ts分别服务于单文件搜索与工作区聚合搜索使用时可对照各自的类型定义。【免费下载链接】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），仅供参考