SwiftFindRefs
Purpose
Use
swiftfindrefs to locate every Swift source file that references a given symbol by querying Xcode’s IndexStore (DerivedData). This skill exists to prevent incomplete refactors caused by text search or heuristics.
Rules
- - Always run
swiftfindrefs before editing any files. - Only edit files returned by
swiftfindrefs. - Do not substitute
grep, rg, IDE search, or filesystem heuristics for reference discovery. - Do not expand the file set manually.
- If IndexStore/DerivedData resolution fails, stop and report the error. Do not guess.
Preconditions
- - macOS with Xcode installed
- Project has been built at least once (DerivedData exists)
- INLINECODE5 available in PATH
Installation
CODEBLOCK0
Canonical command
Prefer providing
--projectName and
--symbolType when possible.
CODEBLOCK1
Optional flags:
- -
--dataStorePath <path>: explicit DataStore (or IndexStoreDB) path; skips discovery - INLINECODE9 : enables verbose output for diagnostic purposes (flag, no value required)
Output contract
- - One absolute file path per line
- Deduplicated
- Script-friendly (safe to pipe line-by-line)
- Ordering is not semantically meaningful
Standard workflows
Workflow A: Find all references
- 1. Run
swiftfindrefs for the symbol. - Treat the output as the complete reference set.
- If more detail is needed, open only the returned files.
Workflow B: Fix missing imports after moving a symbol
Use
swiftfindrefs to restrict scope, then add imports only where needed.
CODEBLOCK2
Then for each printed file:
- - Insert
import <ModuleName> in the imports block at the top. - Preserve existing import ordering/grouping.
- Never add duplicate imports.
- Do not reformat unrelated code.
Workflow C: Audit usage before deleting or renaming a symbol
- 1. Run
swiftfindrefs for the symbol. - If output is empty, treat the symbol as unused (still validate via build/tests if needed).
- If non-empty, review the listed files before changing public API.
References
- - CLI details: references/cli.md
- Playbooks: references/workflows.md
- Troubleshooting: references/troubleshooting.md
SwiftFindRefs
目的
使用 swiftfindrefs 通过查询 Xcode 的 IndexStore（DerivedData）来定位所有引用给定符号的 Swift 源文件。此技能旨在防止因文本搜索或启发式方法导致的不完整重构。
规则
- - 在编辑任何文件之前，始终运行 swiftfindrefs。
- 仅编辑 swiftfindrefs 返回的文件。
- 不得使用 grep、rg、IDE 搜索或文件系统启发式方法替代引用发现。
- 不得手动扩展文件集。
- 如果 IndexStore/DerivedData 解析失败，请停止并报告错误。不要猜测。
前置条件
- - 已安装 Xcode 的 macOS 系统
- 项目至少已构建一次（DerivedData 存在）
- swiftfindrefs 在 PATH 中可用
安装
bash
brew tap michaelversus/SwiftFindRefs https://github.com/michaelversus/SwiftFindRefs.git
brew install swiftfindrefs
标准命令
尽可能提供 --projectName 和 --symbolType。
bash
swiftfindrefs \
--projectName \
--symbolName <符号名称> \
--symbolType
可选标志：
- - --dataStorePath <路径>：显式指定 DataStore（或 IndexStoreDB）路径；跳过自动发现
- -v, --verbose：启用详细输出以进行诊断（标志，无需值）
输出约定
- - 每行一个绝对文件路径
- 去重处理
- 脚本友好（可安全地逐行管道传输）
- 排序无语义意义
标准工作流程
工作流程 A：查找所有引用
- 1. 对符号运行 swiftfindrefs。
- 将输出视为完整的引用集。
- 如果需要更多详细信息，仅打开返回的文件。
工作流程 B：移动符号后修复缺失的导入
使用 swiftfindrefs 限定范围，然后仅在需要的地方添加导入。
bash
swiftfindrefs -p <项目> -n <符号> -t <类型> | while read file; do
if ! grep -q ^import <模块名称>$ $file; then
echo $file
fi
done
然后对每个打印的文件：
- - 在顶部的导入块中插入 import <模块名称>。
- 保留现有的导入排序/分组。
- 切勿添加重复的导入。
- 不要重新格式化无关代码。
工作流程 C：删除或重命名符号前审计使用情况
- 1. 对符号运行 swiftfindrefs。
- 如果输出为空，则将该符号视为未使用（必要时仍通过构建/测试验证）。
- 如果非空，在更改公共 API 前审查列出的文件。
参考资料
- - CLI 详情：references/cli.md
- 操作手册：references/workflows.md
- 故障排除：references/troubleshooting.md
