pi-web-git-graph

一个 pi-web 插件,在 workspace 面板里渲染 GitKraken / vscode-git-graph 风格的提交图:分支、合并、标签泳道,点开看每提交的文件改动与 diff,并支持检出 / 从提交新建分支。

它能做什么

• 提交 DAG 图:按 git log --all 绘制,自动分配泳道,合并用曲线连接,分支/标签用彩色 pill 标注(HEAD 带高亮环)。
• 提交详情:点任意提交 → 显示作者、时间、变更文件列表(增/删/改/重命名状态),以及完整 diff(绿加红减着色)。
• 交互操作:
  • 检出:git checkout <hash>(分离 HEAD)。
  • 从此处新建分支:git branch <name> <hash>。

为什么这么取数据(重要约束)

pi-web 插件 API 有三条硬限制,决定了实现方式:

1. 跑终端命令(terminal.runCommand)拿不到 stdout——handle.completed 只给状态/退出码,不给输出。
2. WorkspaceFiles.readFile 只返回 utf8 文本,读二进制 .git 对象会被破坏。
3. 官方 git 后端只暴露 status/diff,且为 machine-scoped,第三方插件加不了后端、也不能可靠复用。

所以本插件走唯一可行的路:用 git CLI 把数据落到工作区内的缓存文件(<workspace>/.gitgrapher/*.txt),再用 files.readFile 读回来解析。交互操作则通过终端命令直接触发(不需要读输出)。

安装

推荐（发布版）：在 PI WEB 的 Settings → Pi packages 填入 github:samecorner/pi-web-git-graph，或命令行 pi install github:samecorner/pi-web-git-graph。需要：

• 机器上装有 git 且在 PATH 中。
• panel API v2 的 terminal.runCommand（workspace 面板 context 上的稳定 API）。
• git ≥ 2.36（git worktree list --porcelain -z）。

也可以把本目录（或 pi-web-git-graph.zip）手动放到 ~/.pi-web/plugins/pi-web-git-graph/ 加载。

已知限制 / 待真机验证

• 数据通过缓存文件回读,readFile 路径语义在不同版本可能是相对或绝对(代码已做回退)。
• 每次用户交互只发 1 个终端命令(打开图 / 点提交各 1 条,内部用 ; 串联全部 git 读取),缓存文件按调用唯一命名、读后自动删除。
• 隐藏终端用完后由插件立即删除(同源内部 DELETE 端点,失败无害)——不在 Terminal 面板留下任何条目。该端点是内部实现,pi-web 升级后如失效,退回方案:终端堆积时手动清理/重启 sessiond。
• git 命令失败(退出码非 0)会抛错,面板显示 git 的 stderr;git log 无提交(空仓库)按空图处理。
• 每个 git 命令有 30s 超时,超时抛错(终端内命令不会被杀死,仍在后台完成)。
• 默认最多取最近 2000 个提交(loadGraph(context, maxCount))。
• 泳道分配为近似算法(线性历史单泳道、分支按 tip 数封顶),拓扑正确但不保证与 git-graph 完全一致的紧凑度。
• 首次运行会把 .gitgrapher/ 写入 .git/info/exclude,避免污染 git status。

文件

• pi-web-plugin.js — 入口,贡献 workspace.git-graph 面板与打开/刷新动作。
• git-graph-panel.js — 面板自定义元素(加载、渲染、选提交、交互操作)。
• git-data.js — git 数据获取与解析(命令→缓存文件→读回)、检出/建分支。
• git-graph-layout.js — 泳道/边分配算法。
• git-graph-render.js — SVG 图渲染。