Git 提交图 aski0006/dsh-git-graph-panel

dsh-git-graph-panel

给 DSH Web 的右侧栏启动页加一张 Git Graph 卡片：一眼看出当前项目是不是 Git 仓库；是的话，直接把提交图画出来（泳道、合并分叉、分支/标签胶囊、脏文件计数）。

DSH >= 0.2.1-rc.2 · React ^18.2 · 零运行时依赖 · 图是手写 SVG，不引入绘图库

界面

打开后是一张普通标签页，顶栏一行状态，下面是提交列表：

Git Graph ● master 3 个改动未提交 12 个提交 ⟳ ───────────────────────────────────────────────────────────────────────── ● Merge branch 'feature' master v1.0 23484c0 · Asaki · 1 分钟前 ●─┐ feat: 分支上的提交 feature a8b772e · Asaki · 3 分钟前 │ ● fix: 主线的提交 8f21c0d · Asaki · 5 分钟前 ●─┘

- 左栏是画出来的泳道：每个提交一个圆点，同一分支保持在同一列，合并提交向右支出新列，合并边按父提交序号从曲线接到子提交；父提交不在本次窗口里时画虚线连到行边。
- 每行右侧是「短 SHA · 作者 · 相对时间」，点 SHA 直接复制完整提交号。
- 分支/标签/HEAD 显示为胶囊，当前分支高亮；HEAD 与分支重合时合并成一个胶囊。
- 顶部状态条：当前分支、改动文件数、冲突数、提交数；超过上限时提示「仅显示最近 N 条」。
- 中英文随 DSH 的 locale 切换，颜色全部走 --dsw-alias-* 主题令牌，深浅色主题都不用另配。

安装

dsh plugin 只是把参数转给 profile 目录里的 pnpm，所以本地目录用 link: 装进去：

dsh plugin add --profile desktop "link:<本仓库绝对路径>"

也可以在 DSH 的插件管理界面里安装/启用本地包。插件本体就是一个 DSH bundle，cordis.patch.yml 只做一件事——插一行：

- insert:
- id: git-graph-panel
name: 'dsh-git-graph-panel'

安装完要重启 DSH（host 半端只在启动时加载），之后右侧栏启动页（Start）里就会出现 Git Graph 卡片。

使用

右侧栏 → 启动页 → 点 Git Graph 卡片，右栏开一个独立标签页。

标签页用当前会话的项目目录（sessions 快照里的 cwd）作为仓库起点；没有会话目录时回落到第一个 workspace。目录不是仓库、没装 git、仓库还是空的、HEAD 未出生，都会给出各自的空状态和一句怎么修。

工作原理

插件分两半，浏览器半端不碰 git，host 半端不碰 UI：

| 文件 | 运行位置 | 职责 |
| lib/index.js | host（Node，ESM） | 注册路由；按目录跑 git；解析 log / for-each-ref / status；返回一份仓库视图 |
| lib/client.js | 浏览器 | 注册标签页类型、启动页卡片、正文与标题三个插槽；把提交数据排成泳道并画 SVG |

数据流：GitGraphBody 取 sessionId → cwd → GET git-graph-panel/data?path=… → host 跑 git（rev-parse 四次、log、for-each-ref、status）→ 一份 JSON → 客户端排泳道、画图。

路由

| 路由 | 方法 | 说明 |
| /git-graph-panel/data | GET / POST | 仓库视图。目录从 ?path= 查询串或 { path } 请求体取，都没有就用第一个 workspace |
| /git-graph-panel/reload | POST | 从磁盘重读本包的浏览器 bundle 并刷新它的 revision（之后刷新窗口即可看到改动） |

两条路由都只接受回环地址的请求，其余一律 403 { ok: false, error: "forbidden" }；读失败不会抛异常，而是 { ok: false, isRepo: false, reason, detail }，reason 取 not-repo / no-workspace / git-missing / git-error。

数据形状

{
"ok": true,
"dir": "D:/test/test-git",
"isRepo": true,
"root": "D:/test/test-git",
"branch": "master",
"detached": false,
"head": "23484c0",
"empty": false,
"dirty": 1,
"conflicts": 0,
"branches": [{ "name": "master", "current": true, "sha": "23484c0…" }],
"commits": [
{ "sha": "23484c0…", "short": "23484c0", "subject": "Merge branch 'feature'", "author": "Asaki", "time": 1761000000, "parents": ["…", "…"],
"refs": [{ "name": "master", "kind": "head" }, { "name": "v1.0", "kind": "tag" }] }
],
"truncated": false,
"limit": 120
}

git log 用 \x1f / \x1e 当字段与记录分隔符（控制字符不会被 commit message 干扰），窗口上限 120 条、单条命令输出上限 1 MiB。

为什么自己画

git log --graph 的 ASCII 图在等宽字体里能用，但塞进面板会散架：列宽随字符走、合并线只有 |/\\ 三种笔画、颜色只有终端 16 色。手写 SVG 换来的是一屏固定的 14px 泳道、可以着色的分支线、能点能选的提交行，也不需要为一个只画直线的图去背一个绘图库的体积。

目录结构

dsh-git-graph-panel/
├── lib/
│ ├── index.js # host：git 读取 + 路由 │ └── client.js # 浏览器：标签页 / 插槽 / 泳道 / SVG ├── cordis.patch.yml # bundle 装配 ├── icon.svg └── test/ ├── run.mjs # 跑全部套件 ├── test-parsers.mjs ├── test-graph.mjs ├── test-render.mjs ├── live-render.mjs ├── test-host.mjs └── log.txt / branches.txt / status.txt # 真实 git 输出固定成夹具

开发

npm test # 全部套件
node test/live-render.mjs # 只跑"真渲染"

- test-parsers.mjs：用固定夹具跑 git log / for-each-ref / status 解析器（含重叠 ref、合并提交双父、超过 120 条的截断）。
- test-graph.mjs：泳道算法——线性历史同列、合并行出列、父提交不在窗口内落到 -1。
- test-render.mjs：在最小 React 运行时里加载真实 bundle，断言注册了一个标签页类型、三个插槽、点卡片会 openTab('git-graph', { replaceTab: true })。
- live-render.mjs：更狠一层，用假 fetch 喂一份录好的真实 payload，把整棵组件树渲染成文本，断言 9 个圆点、8 段路径、分支/标签胶囊与提交标题都在。
- test-host.mjs：假 webServer + 假 subprocess 接缝，跑通整条 host 读路径，并覆盖 POST 传目录、非回环地址 403、目录不存在、未知子路径 404、/reload 有/无 registry 两种情形。

客户端改动不必重启应用：curl -X POST http://127.0.0.1:<port>/git-graph-panel/reload，再刷新窗口即可看到新 bundle；host 改动仍需重启 DSH（host 插件只在启动时加载）。

手工验证数据接口：

curl "http://127.0.0.1:<port>/git-graph-panel/data?path=D%3A%2Ftest%2Ftest-git"

开发坑：在 DSH 的 bash 沙箱里执行 git merge 会因 cannot create standard output pipe for stash: Permission denied 失败，造"带合并提交"的夹具仓库请用 plumbing：
git commit-tree <tree> -p -p -m "merge" 再 git update-ref。

已知限制

- 只读：不提供 checkout / stage / commit / push，任何写操作请用终端。
- 单仓库：只画当前项目目录所在的仓库，不处理子模块和多仓库工作区。
- 提交窗口 120 条；更长的历史只显示最近的一段（会有"仅显示最近 N 条"提示）。
- 泳道数没有上限，历史非常"开花"的项目左侧图形区会变宽，挤压提交标题。
- 只解析默认的 git log 输出，不跟随 reflog / stash。

许可

源码公开，但不是开源项目：本项目使用 PolyForm Noncommercial License 1.0.0 （见 LICENSE）。

- 可以：个人使用、学习研究、 hobby 项目、慈善/教育/公共机构使用，以及在这些范围内的修改与分发（分发时要带上本许可证或它的链接）。
- 不可以：任何商业用途。公司内部使用、打包进商业产品、对外提供付费服务，都算商业用途。
- 商用授权请联系作者（GitHub @aski0006）。

A DSH web plugin that adds a Git Graph card to the right sidebar's Start tab.
It resolves the session's project directory, asks the host half whether that
directory is a Git repository, and — when it is — draws the commit graph (lanes, merge edges, branch/tag chips, dirty and conflict counts) as hand-written SVG, so the plugin ships with no drawing dependency.

Install with dsh plugin add --profile <name> "link:<this directory>" and restart DSH. The host half
exposes GET|POST /git-graph-panel/data (loopback only) and runs git through
the harness subprocess seam when it is available. npm test covers the parsers,
the lane layout, tab/seat registration, a full render pass and the host route.