使用教程
August 14, 2026 · View on GitHub
本文档说明 Git 变更摘要面板的每个部分以及常见操作。
English: USAGE.md
打开与关闭面板
- 点击会话头部、Session log 旁边的 ⑂ 按钮打开面板；再点一次、或点面板右上角 ✕ 关闭。
- 面板顶部有 ⟳ 刷新 按钮，手动重新计算。
仓库定位
面板打开的仓库由以下规则决定：
- 自动探测（默认）：从当前会话工作区开始，向上查找最近的 git 仓库（
git rev-parse --show-toplevel）。例如工作区是/home/user/proj/subdir而仓库在/home/user/proj，会自动定位到仓库根目录。 - 手动指定：在顶部输入框填入仓库路径，回车或点 应用。
- 自动跟随工作区：切换 DSH 工作区后，面板自动清空旧数据并按新工作区重新计算；手动指定过路径时会继续使用该路径。
面板内容详解
概览卡片（顶部）
| 卡片 | 含义 |
|---|---|
| 文件数 | 相对 HEAD 有变更的文件总数（含二进制） |
| 新增行 | 相对 HEAD 新增的总行数（绿色） |
| 删除行 | 相对 HEAD 删除的总行数（红色） |
| 净变化 | 新增 − 删除（带正负号） |
| 未跟踪 | 未跟踪文件数量（git ls-files --others） |
元信息
- 仓库：实际使用的仓库根目录
- 基分支：自动探测的分支（upstream →
origin/<当前分支>→origin/main→origin/master→main→master→develop），用于计算"分支提交" - upstream：远程跟踪分支，以及领先（+）与落后（−）的提交数
- HEAD：短 hash、提交信息、作者、提交时间
未提交变更（可折叠区块）
- 未提交变更（相对 HEAD）：工作区所有未提交修改的总和（已暂存 + 未暂存）
- 已暂存 (staged)：
git add过的部分 - 未暂存 (unstaged)：改了但还没
git add的部分
每个文件一行：状态徽标 + 路径 + +x −y 行数（二进制文件显示"二进制"）。
状态徽标图例
| 徽标 | 含义 | 颜色 |
|---|---|---|
| 改 M | 修改 | 中性灰 |
| 增 A | 新增 | 绿色 |
| 删 D | 删除 | 红色 |
| 移 R | 重命名（旧路径 → 新路径） | 琥珀 |
| 新 U | 未跟踪 | 灰 |
分支提交（领先基分支）
- 当前分支领先基分支的提交列表（hash + 提交信息，不含 merge 提交）
- 这些提交合并起来的差异统计（文件数 / +行 / −行）
文件明细（按变更量排序）
- 变更最多 TOP5：按（新增+删除）行数最大的 5 个文件
- 按扩展名：如
.py、.js、.md各自的文件数和行数变化 - 按顶层目录：仓库顶层目录维度的聚合统计
附加检查
- 未跟踪文件：数量 + 前 10 个路径
- 二进制文件：无行数统计、只计文件数的变更
- 冲突标记：
git diff --check发现的<<<<<<<冲突标记数量（琥珀色告警） - 空白错误：
git diff --check报告的空白错误数量 - 最近提交：仓库最近 5 条提交（hash + 信息）
调试区（仅异常时显示）
当发生错误或走了环境降级（attempt > 1）时，面板底部会显示灰色小字调试区：
repo/start/fallback：实际使用的仓库路径、探测起点、兜底根目录attempt：命中的执行级别（1 默认 / 2 标准 PATH / 3 无沙箱 / 4 subprocess 直连）probe：插件环境里的 PATH 与git/bash/sh解析结果branchErr/headErr：失败命令的错误信息
正常情况（默认路径、无错误）不显示调试区。
常见操作
| 操作 | 方法 |
|---|---|
| 重新计算 | 点面板顶部 ⟳ |
| 切换仓库 | 输入框填路径 → 回车 / 应用 |
| 回到自动探测 | 清空输入框 → 应用 |
| 折叠/展开区块 | 点击区块标题 |
| 看完整文件列表 | 区块内列表可滚动（最多约 220px 高） |
主题与配色
面板使用 DSH 主题 token（--dsw-alias-*），自动跟随 DSH 的浅色/深色主题：
- 面板/卡片/分区背景：
bg-overlay/bg-layer-1/bg-layer-2 - 文字：
label-primary（主要）/label-secondary（次要） - 语义色：新增绿
#22c55e、删除红#ec1313、冲突/警告琥珀#f59e0b