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 六条命令。

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 都能用

页面会自动二选一：

设置

已知限制

• 只读是设计：不暂存、不提交、不切分支、不 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。

English