Issue 18

Issue #18：[功能] 支持新增文件的差异预览

Issue #18 · PR #23 · 实现方案与验收记录

2026-09-16 从 Issue 迁入的需求与方案快照，保留原始验收勾选状态；当前进度以关联 Issue / PR 为准。实现细节、验收证据和未验证项见上方记录。

背景与问题

在远端仓库新建尚未跟踪的文件后，改动列表能够显示该文件，但点击「查看差异」无法展示新增内容，用户需要先暂存或离开应用才能检查文件。

代码核对基线：development@30d9947。当前单文件预览统一调用普通 git diff -- <path>，该命令不包含未跟踪文件；返回空内容时，检查器会显示「请选择改动文件或提交以查看差异」。

目标

新增文件无需先暂存即可查看差异；参考 GitLens，以空版本对比新增内容，并保持暂存前后正确的 Diff 语义。

需求与范围

• 未跟踪文件（untracked / ??）：点击文件即可预览；旧版本为空，新版本为远端工作区中的当前内容，文本内容全部标记为新增。
• 已暂存的新增文件（added / A）：查看暂存区实际内容相对空版本的差异；如果暂存后再次修改，区分已暂存内容与后续未暂存改动，不能错误地混用工作区内容。
• 复用现有单栏、分栏和放大查看能力；切换文件、暂存、取消暂存及刷新后，预览与最新状态一致。
• 空文件明确显示「新增空文件」等状态；二进制或超出预览限制的文件给出明确提示；读取失败或文件已消失时显示对应反馈。
• 查看差异是只读操作，不应通过临时 git add 等方式改变远端工作区或暂存区。

方案建议与代码线索

• 当前入口：ChangesView.tsx、RepositoryDetailPage.tsx。差异获取：GitCommands.diff；展示与空状态：DiffViewer.tsx。
• GitLens 参考：diffWith.ts 对缺失的旧版本使用 deletedOrMissing，由 fsProvider.ts 返回空内容，再交给差异编辑器展示新增内容。
• 候选方案：识别未跟踪状态，读取远端文件并与空内容比较，或生成兼容现有检查器的新增文件补丁。若采用 git diff --no-index，需将退出码 1 识别为「存在差异」，并处理空文件、二进制及路径参数。具体实现方式在开发时确定。

验收标准

• 新建非空文本文件后，无需暂存即可查看全部新增内容，单栏、分栏和放大查看均正常。
• 新文件暂存、取消暂存及暂存后再次编辑时，各状态对应正确的比较内容；预览过程不改变文件内容和 Git 状态。
• 空文件、二进制文件、超出预览限制和读取失败有明确反馈，不误显示为尚未选择文件。
• 中文、空格及常见特殊字符文件名、子目录内的新文件均可按文件正确预览。
• 连续切换文件或仓库、刷新远端状态后，不残留上一个文件的预览；已有修改、删除和提交历史 Diff 不回退。

验证方案

使用隔离的远端测试仓库，新建普通文本、空文件、二进制文件及带空格／中文名称的文件，执行「未跟踪 → 暂存 → 再编辑 → 取消暂存」流程，对照工作区和暂存区内容检查预览。覆盖尚无首次提交的仓库、加载失败及快速切换，并在 Web 和桌面端验证主要交互。

风险与待确认

文本大小与编码限制、二进制提示的具体样式待实现时确定。现有状态解析可能将未跟踪目录聚合为一项，需保证可定位其中的单个文件；远端读取和命令参数处理应限定到当前仓库的目标文件。

补充资料

用户要求与「新增文件可删除」拆分为两个功能 issue，两项均参考 GitLens 实现。以上为需求与源码分析，尚未实施或完成运行验证。