VSCode插件应通过Git扩展API监听工作树变更，而非自行文件系统监听；需声明"workspaceContains:.git"激活事件，订阅repository.state.onDidChange事件并按需调用repository.status()获取git status --porcelain=v2数据，避免轮询导致性能问题。
VSCode插件如何监听 Git 工作树变更
插件不能直接 hook 文件系统事件，必须通过 VSCode 提供的 git.extension API 或底层 git.status --porcelain 调用来感知变更。VSCode 的 Git 扩展暴露了 GitExtension 实例，插件可通过 vscode.extensions.getExtension('vscode.git')?.exports 获取——但注意该导出仅在 Git 扩展启用且项目含 .git 时才可用。
常见错误是插件启动时立即尝试访问 getAPI(1)，而此时 Git 扩展可能尚未完成初始化，导致返回 undefined。正确做法是监听 vscode.extensions.onDidChange 并轮询检查，或使用 vscode.workspace.onDidOpenTextDocument + vscode.workspace.onDidChangeWorkspaceFolders 触发延迟加载。
- 必须在
activationEvent中声明"onStartupFinished"或"workspaceContains:.git"，否则插件不会在 Git 仓库中自动激活 - 不要自行启动
inotify或FSEvents监听器——VSCode 已统一管理，重复监听会导致 CPU 暴涨 -
git.status --porcelain=v2是唯一推荐的解析入口，v1格式已不保证字段顺序，易解析失败
如何安全读取当前分支与 HEAD 状态
直接读取 .git/HEAD 文件风险极高：它可能是符号引用（如 ref: refs/heads/main），也可能是分离 HEAD 的 commit hash。插件应调用 git.branch 命令或复用 Git 扩展的 repository.state.HEAD 属性，而非自己解析文件。
一个典型坑点是假设 HEAD 总指向分支名。当处于 git checkout abc123 状态时，repository.state.HEAD 是 null，而 repository.state.isDetached 才为 true。忽略这点会导致 UI 显示 “Branch: undefined” 或崩溃。
- 始终用
repository.state.HEAD?.name取分支名，而非repository.state.HEAD本身 - 分离 HEAD 下的提交信息需额外调用
git.show获取作者、时间等，不能只依赖HEAD内容 - 多工作树（
git worktree）场景下，每个Repository实例对应一个独立工作树，vscode.gitAPI 会自动识别.git/worktrees/下的路径
避免触发高开销操作的轮询策略
默认情况下，VSCode 的 Git 扩展每 1000ms 执行一次 git status。插件若自行轮询，极易叠加造成卡顿，尤其在大仓库中。正确的做法是订阅 repository.state.onDidChange 事件——它由 Git 扩展内部状态机触发，天然去重且节流。
该事件不包含完整差异数据，只表示“状态可能变了”。你需要按需调用 repository.status() 获取最新 git status --porcelain=v2 输出，而不是每次事件都拉全量状态。
- 不要用
setInterval(() => repo.status(), 2000)——这是最常被踩的性能雷区 - 如果插件需高频响应（如实时 diff 预览），应在
onDidChange后加防抖（setTimeout+clearTimeout），延迟 300ms 再执行实际逻辑 -
"git.refreshInterval": 5000这类用户设置会影响底层轮询频率，插件无需也不应覆盖它
处理未暂存/未跟踪文件的边界情况
VSCode 的 git.status --porcelain=v2 输出中，未跟踪文件标记为 ??，但插件常误以为它们“不属于 Git 管理”。实际上，这些文件可能已被 .gitignore 排除，也可能只是临时生成物。直接对 ??. filename 行执行 git add 会失败。
更可靠的方式是调用 repository.getWorkingTreeGroup() 和 repository.getUntrackedGroup()，它们返回已过滤、可操作的 SourceControlResourceGroup 对象，内部已处理 ignore 规则和 submodule 边界。
- 永远别手动解析
--porcelain输出来判断文件是否可添加——getUntrackedGroup()返回的列表才是真实可操作集合 - 对
repository.sourceControl.inputBox.value的修改不会自动触发状态刷新，需显式调用repository.status() - 当用户在外部终端执行
git clean -fd后，插件监听的文件系统事件可能滞后，此时应依赖onDidChange事件而非 fs.watch
真正难的不是读取状态，而是理解 VSCode Git API 的“状态驱动”本质：它不提供实时流，而是用事件+懒加载组合应对各种边缘场景。多数插件崩溃或卡顿，都源于试图绕过这层抽象，直接跟 Git CLI 较劲。
