Git 提交图谱 AFunDog/dsh-sidebar-git-graph

dsh-sidebar-git-graph

给 DSH（DeepSeek Harness） 加一个右侧栏页面：把当前会话的仓库画成分支/合并关系图 （VS Code 风格 —— 彩色泳道、分叉与汇入的贝塞尔曲线、ref 芯片、点开看提交详情），并在它上方给出工作树改动区。

只读：不 checkout、不 commit、不 reset、不 rebase、不 fetch/push、不 add、不 restore、不 worktree add/remove/prune。
只跑 rev-parse、status、for-each-ref、log、diff、worktree list 六条命令。

Git 图谱页面：彩色泳道、ref 芯片、提交行，上方是工作树「更改」区

深色主题下的同一页面：泳道配色由主题令牌派生

English。参与开发、想了解内部实现或踩坑记录，请看 AGENTS.md。

特性

- 工作树改动，VS Code 式两段：图上方的更改与暂存的更改（合并中还会多出合并更改），每行带状态字母（M/A/D/R/C/U）与增删行数；点一行就地展开它的 diff，两段可折叠且记得住。
- 一眼看清多分支关系：并发的每条历史线占一条泳道，分叉/汇回处画曲线，合并提交的圆点更大，当前 HEAD 所在泳道更醒目。
- 每个提交带 ref 芯片：本地分支 / 远程分支 / 标签；当前分支用主题的品牌色填充，文字用主题里与它配对的那支前景色。
- 一个工作区，多个仓库：工作区里同时躺着好几个仓库是常态（本插件自己的 checkout 就在 vendor/@zeng/ 下挂着一个嵌套仓库）。这时头部会长出一个下拉框，列出找到的每个仓库，选择按工作区记忆。工作区自己只是某个仓库的子目录也没问题——外层那个仓库同样会被列出来。
发现过程不会跑出工作区：只向下扫，且层数、目录数、仓库数、耗时四个闸门都封着。
- 同一个仓库的每个工作树：一个仓库可以有多个工作树（git worktree add），各有各的分支、各有各的未提交改动，而关联工作树通常根本不在工作区目录里（这个功能就是为一对兄弟目录 的工作树做的）。下拉框把它们全列出来，每一项标着它自己的分支，可以自由切换，切换后看到的就是这个工作树自己的图谱与改动。主工作树、分离头、被 lock 的工作树都有标记；目录已经不在的工作树不列出、但会在提示里给出条数，不会悄悄少一个。清单来自 git worktree list，所以从任意一个工作树出发都能看到全集——站在关联工作树里，主工作树同样可选。
- 头部信息：仓库名、当前分支、↑ahead ↓behind、脏文件数。
- 远端信息过期会告诉你：图谱画的是本地仓库，本页绝不碰网络——这正是「只读」承诺的一部分。
所以远端上刚发生的合并，在有人跑过 git fetch 之前这里看不见。页面不会让你对着图猜「是不是画错了」，而是直接说明仓库上次 fetch 距今多久（6 小时内）、哪些本地分支落后于上游。从未 fetch 过的仓库会如实报告「没有远端」，而不是「信息过期」。
- 提交信息搜索：高亮命中并逐个跳转（不过滤列表 —— 过滤会打断泳道连续性，那正是这个页面的意义）。
- 点行看详情，并且直接列出这个提交改了哪些文件：完整 sha、作者与邮箱、绝对时间、父提交、参与的 refs；下面就是改动文件清单——状态字母（A/M/D/R/C/T）、重命名显示原名、每个文件的 +/− 行数，点某个文件就地展开它的 patch（与「更改」区同一套渲染与手感）。
合并提交按第一父提交比较，标题里会写明这一点（否则你会以为那些文件是这个合并自己写的）；二进制文件在展开时说「二进制文件，无法显示改动」，而不是给你一个空 diff。
- 虚拟列表：窗口内最多 2000 条也只渲染可见行；页面不是当前标签页时完全不发请求。
- 错误态有话说：不是 git 仓库 / PATH 里没有 git / 拿不到工作目录 / 被信任围栏拒绝 / git 失败，各有各的文案，不给你一片空白。
- 零依赖、零构建：宿主半是纯 ESM，浏览器半是手写的单文件 client bundle。
lib/ 里读到的就是实际跑的代码，没有构建产物与源码的偏差。
- 跟随会话的 worktree 标签：装了并启用 @zeng/dsh-session-worktree 时，页面默认画该会话打了标签的那个工作树，而不是工作目录碰巧所在的那个仓库。
仓库优先级：你在下拉里手点的 → 会话的 worktree 标签 → 这个工作区上次记住的仓库 → 工作目录所在的仓库 → 扫到的第一个。页面会说明「正在跟随标签」；用不了时说得更清楚（目录没了 / 不是仓库根 / 出了本页可访问范围）—— 绝不静默换一个仓库还不吭声。
卸载或停用那个插件，行为与以前完全一致。

安装

dsh plugin --profile web add github:AFunDog/dsh-sidebar-git-graph

装完重启 dsh web（宿主半要挂路由），再硬刷新浏览器。打开右侧栏选「Git 图谱」——装了 dsh-better-sidebar 时它在 + 菜单里；裸 DSH 下就在侧栏的引导页上（该格已经放着引导页时 + 控件不会绘制）。
页面跟随你正在看的会话：切会话就重新读那个会话的工作区。

钉版本 / 从本地克隆安装

用 tag 安装（推荐：lockfile 会记下解析到的 commit）
dsh plugin --profile web add github:AFunDog/dsh-sidebar-git-graph#v0.2.0

从本地克隆安装（只接受绝对路径 —— 相对路径会被 spec 解析器拒绝）
dsh plugin --profile web add /path/to/dsh-sidebar-git-graph

装没装 dsh-better-sidebar 都能用

页面会自动二选一：

| 你的环境 | 行为 |
| 装了 dsh-better-sidebar | 走它的公开扩展点 ctx.betterSidebar.registerTab：出现在 + 菜单，并在设置 → 侧边卡片里得到一张卡片（开关 + 一个「每次加载条数」的插件设置），名字是「Git 图谱」。 |
| 裸 DSH | 走 DSH 原生的侧栏 tab 类型（ctx.sidebarRightTabs + sidebar.right.pane.tab 槽）：同一列、同一个 + 菜单，只是没有那张设置卡片。 |

设置

| 设置 | 位置 | 默认 | 含义 |
| 每次加载的提交数 | 设置 → 侧边卡片 → Git 图谱 → 功能设置（仅 dsh-better-sidebar） | 400 | 100–2000。越大越完整，首次读取越慢。 |
| 仓库扫描层数 | 同上 | 5 | 0–8。往工作区里找几个仓库供下拉选择；0 = 不扫，只认工作目录所在的仓库。工作区特别大导致清单扫不全时，把它调小。 |
| 历史范围 | 页面头部 | 全部分支 | 全部分支 / 仅当前分支。 |
| 提交搜索 | 页面头部 | — | 高亮命中并逐个跳转。 |

已知限制

- 只读是设计：不暂存、不提交、不切分支、不 push。要改工作树就用别的工具。
- 未跟踪文件没有 +/− 计数：git diff --no-index 只比较两个路径，要行数就得每个文件起一个进程 （一个还没 add 过的仓库里可能是几百次）。所以段头只统计拿得到计数的行，拿不到的留空，而不是印一个会被读成「没有改动」的 0。一个文件两侧都改过（MM）会同时出现在两段——那正是这两段的含义。
- 内嵌的独立仓库是一行不可点的目录：git 不会下钻进「仓库里的仓库」（-uall 也不下钻），所以外层仓库只看得见一个目录，它没有 diff 可显示。页面在那一行上说明原因，而不是点了没反应。
- 上限：一次最多 3000 行改动、单个文件最多 512 KiB patch；两者都会在页面上如实说明，而不是悄悄截掉。
- 窗口有上限（单次最多 2000 条，默认 400）；更老的历史会明确提示「被截断」，而不是静默丢弃。
- 仓库发现是有上限的扫盘：层数、目录数、仓库数、耗时四道闸门，踩到任何一条都会在页面上如实说明（而不是假装清单就是全的）；解决办法是把扫描层数调小。显然不会住着「想单独画的仓库」的目录（node_modules、target、.venv、构建产物…）不向下递归——但每个仍会 stat 一次，所以一个恰好叫 build 的仓库不会被漏掉。
- 下拉里只会出现从工作区够得到的仓库：工作区自身、它里面的、把它包住的那个，以及 工作区所属仓库的工作树（以 git worktree list 为准）。别的路径即使浏览器点名，宿主也会拒绝；并且会用 rev-parse 复核它确实是仓库根。
- 工作目录被删了就不再拿它当工作区：会话/标签页手里的那个路径可能是一条已经删掉的关联工作树（活干完就删是常态）。宿主会跳过它、改用仍然存在的候选继续画，并在页面上说清「上次的工作目录（…）已经不在了，这次改画 …」——而不是整页只剩一句「工作目录不存在」。
- 每个工作树各读各的：git status 与 git log 都是按工作树算的，所以每个工作树显示自己的分支、自己的未提交改动、自己的 HEAD；页面从不把两个工作树合成一份。
目录已不在的（prunable）与裸仓库不列出，只在提示里给出条数。
- 提交的文件清单有上限：一个提交最多列 2000 个文件（初始提交在大仓库上可能有上万个），超了会写明「共 N 个，只列了前 M 个」，绝不悄悄少列。合并提交列的是相对第一父提交的改动（与 VS Code 同口径）；空提交如实说「没有任何文件改动」。
- 搜索不过滤图（理由见特性一节）。
- 泳道配色由 DSH 主题令牌 + color-mix() 派生；不支持 color-mix() 的浏览器退化为四个主题状态色循环。
- 在 DSH 0.1.7-rc.2 + dsh-better-sidebar 0.21.1 上真机验证过；原生回退路径有同一套测试覆盖，但真机使用得少一些。
- npm 上的 dsh-git-graph 是另一个作者的另一个插件（enoughpower/dsh-git-graph）。
本插件是 @zeng/dsh-sidebar-git-graph，目前只从 GitHub 分发。

开发

没有构建步骤：改 lib/ → 宿主半改动重启 dsh web，浏览器半改动硬刷新即可（bundle 的 rev 从文件 mtime 重新推导，刷新就会拿到新内容）。

npm test # = node scripts/test.mjs：先 node --check 每个 lib 文件，再逐个跑测试

路线图、内部结构、泳道算法不变量与 21 条踩坑记录都在 AGENTS.md。

许可

MIT，见 LICENSE。