ghui 实战教程:如何在终端查看 Diff、写行内评论并一键审批合并 Pull Request
ghui 实战教程:如何在终端查看 Diff、写行内评论并一键审批合并 Pull Request
如果你每天要在 GitHub 上处理大量 Pull Request,反复切换浏览器标签页一定很累。ghui 是一款运行在终端里的 GitHub TUI(终端用户界面)工具,让你全程不离开键盘:在终端中查看 PR 的 stacked Diff、直接在代码行上写行内评论、一键审批(Approve)并合并 Pull Request。本教程带你从零安装,到用 d 打开 Diff 视图、enter 写行内评论、shift+r 提交审批、m 一键合并,完整走通一个 PR Review 流程。
1. ghui 是什么?为什么值得装
ghui 的核心定位是:一个键盘驱动的 GitHub Pull Request 工作台。它把 PR 列表、Diff 审阅、评论、标签管理、草稿切换、合并等操作全部收纳进一个终端窗口,适合以下场景:
- 🚀 每天需要 review 多个仓库 PR 的开发者
- ⌨️ 重度 vim / 键盘党,不想离开终端
- 🔍 需要快速扫过大量 diff、定位评论线程并回复的人
它依赖 GitHub CLI(gh)完成认证和 API 调用,因此前置要求只有一个:系统里安装了 gh 并已完成 gh auth login 登录。
2. 安装 ghui:brew 或 npm 两种方式
方式一:Homebrew 安装(macOS / Linux 推荐)
brew 会安装独立的 ghui 二进制文件,运行时不需要 Bun 或 Node 环境:
brew install kitlangton/tap/ghui
后续升级只需执行:
brew upgrade ghui
方式二:npm 全局安装
npm 包同样会附带平台对应的二进制,无需 Bun:
npm install -g @kitlangton/ghui
方式三:从源码运行(本地开发)
git clone https://gitcode.com/gh_mirrors/gh/ghui
cd ghui
bun install
bun link
安装完成后,在任意目录执行 ghui 即可启动。首次启动时它会拉取你关注的 PR 队列并渲染出主界面。
3. 启动 ghui:认识主界面与基础导航
启动后你会看到按仓库分组的 Pull Request 列表。基础导航键(完整键位见 README.md):
| 按键 | 作用 |
|---|---|
j / k 或 ↑ / ↓ |
上下移动选中项 |
gg / shift+g |
跳到第一条 / 最后一条 PR |
ctrl+u / ctrl+d |
上 / 下半页翻页 |
tab / shift+tab |
切换 PR 队列(Authored / Review requested 等) |
/ |
打开过滤框 |
enter |
展开 PR 详情 |
esc |
返回上一级 / 关闭弹框 |
r |
刷新列表 |
q |
退出 |
选中某条 PR 后按 enter 展开详情,此时它仍保留列表级的全部操作键;也可以直接跳到下一步——打开 Diff。
4. 在终端查看 Diff:d 键进入堆叠视图
在 PR 列表或详情视图按下 d,ghui 会打开当前 PR 的 stacked diff——所有变更文件被纵向堆叠在一个滚动视图里,顶部显示 #PR号 仓库名 与 +新增/-删除 统计(渲染实现见 PullRequestDiffPane.tsx)。
Diff 视图内的高频按键(完整定义见 diffView.ts):
| 按键 | 作用 |
|---|---|
j / k |
逐行移动评论锚点(j 前可加数字,如 15 j 跳 15 行) |
[ / ] |
上一个 / 下一个变更文件 |
f |
打开变更文件导航器(宽屏 ≥130 列时文件面板直接内嵌停靠) |
shift+f |
显示 / 隐藏停靠的文件面板 |
shift+v |
切换 split(左右对比)/ unified(统一)视图 |
w |
切换长行自动换行 |
gg / shift+g |
跳到第一 / 最后一处评论 |
n / p |
在 Diff 评论线程之间跳转 |
zz / zt / zb |
将当前行对齐到屏幕中 / 上 / 下(vim 对齐手感) |
r |
重新加载 Diff |
o |
在浏览器中打开该 PR |
esc |
退出 Diff 视图 |
💡 小技巧:在 split 视图下按
h/l(或左右方向键)可以选择旧侧 / 新侧作为评论锚点,这样行内评论会挂在正确的一边。
5. 写行内评论:enter 建评、v 框选多行
Diff 里每一行都是可评论的,操作路径非常短:
- 定位代码行:用
j/k(或15 j这类数字前缀)把光标移到想评论的代码行; - 新建评论:按
enter——若该行已有评论线程则打开它并追加回复,否则直接弹出评论输入框(CommentModal.tsx); - 输入内容:多行评论按
shift+enter换行,enter(或ctrl+s)保存,esc取消; - 多行范围评论:先按
v选中起始行,再用j/k延伸范围,按enter即可对整段代码发表一条评论(再按v可取消选区); - 跳转已有讨论:审阅他人意见时用
n/p在评论线程之间快速跳转,逐条查看并回复。
评论弹窗的底部会实时显示按键提示(enter save / shift-enter newline / esc cancel),新手跟提示走即可,无需记忆。
6. 审批 PR:shift+r 选择 Approve / Comment / Request Changes
代码看完后,在列表、详情或 Diff 视图按下 shift+r,会弹出 Submit review 审批框(UI 见 SubmitReviewModal.tsx,键位见 submitReviewModal.ts):
- 用
j/k(或上下方向键)在三选一里切换:- Comment——只留意见不表态
- Approve——批准该 PR
- Request changes——要求修改
- 按
enter进入可选的 summary 文本区,输入审批总结(不填直接跳过也可以); - 再按
enter提交审批,shift+enter换行,esc退回动作选择或直接取消。
审批结果(Approve / Request changes)会立即反映到 PR 的状态徽标上,无需刷新。
7. 一键合并:m 打开合并框并确认
审批完成后按 m 打开 Merge 弹框(渲染逻辑见 MergeModal.tsx,完整流程状态机见 useMergeFlow.ts)。
弹框会先异步加载合并状态与仓库允许的合并方式,然后提供这些选项:
| 选项 | 说明 |
|---|---|
| Squash and merge now | 压缩成一个 commit 立即合并并删除源分支(还有 Create a merge commit now / Rebase and merge now) |
| Enable auto-merge | 满足 GitHub 要求后自动合并,可设定时触发 |
| Disable auto-merge | 取消已挂起的 auto-merge |
| Squash and merge (admin) | 管理员绕过检查直接合并(红色高危样式提示) |
操作方式:
j/k选择合并动作;tab/shift+tab(或l/h)在 squash / merge commit / rebase 之间切换;enter确认执行。ghui 会先做乐观更新(界面立刻标记为 Merged),请求失败则自动回滚并弹出错误提示,见 mergeActions.ts。
⚠️ 安全设计:只有 PR 处于 open、非 draft、无冲突、无未决 review、CI 非失败/等待状态时,"立即合并"才会出现;对 Draft PR 合并需要二次确认(会先 Mark ready for review 再合并),防止误操作。
8. 顺手效率技巧:让 Review 全流程留在终端
e:把 PR 交给你的编辑器(可配置editorCommand模板,配合 nvim + diffview 或 VS Code,见 editorCommand.ts 与 README 的配置示例);a:打开该 PR 的 GitHub Actions 运行列表,下钻到 job / step,n/p在失败项之间跳转,排查 CI 不用开浏览器;o:浏览器打开 PR,y:复制 PR 元数据到剪贴板;ctrl+p(macOS 为cmd+k):打开命令面板,所有操作可搜索直达;s切换 draft / ready for review,l管理标签,x关闭 PR(带确认)。
9. 核心模块速查
想了解实现细节,可以从这几个入口入手:
- Diff 键位与评论锚点逻辑:src/keymap/diffView.ts
- Diff 面板渲染与文件堆叠:src/ui/PullRequestDiffPane.tsx
- 合并流程状态机(乐观更新 / 回滚 / draft 二次确认):src/ui/merge/useMergeFlow.ts
- 审批弹框与行内评论弹框:src/ui/modals/SubmitReviewModal.tsx、src/ui/modals/CommentModal.tsx
- 主题配置与偏好持久化:src/themeStore.ts(Linux 默认配置位于
~/.config/ghui/config.json)
10. 常见问题
Q:ghui 需要额外配置才能合并吗?
不需要。它复用 gh 的认证与权限,弹框里只显示你当前账号实际有权限的合并动作。
Q:终端太窄会影响 Diff 吗?
会自适应。宽屏(≥130 列)自动内嵌 Changed Files 停靠面板;窄屏下 f 会改用浮层弹框,shift+v 切 unified 视图更省空间。
Q:能只看自己的 PR 吗?
用 tab / shift+tab 切换 Authored、Review requested 等队列,或按 / 过滤,f 打开范围过滤框。
总结
ghui 把 PR Review 的三件套——看 Diff、写行内评论、审批合并——压缩成了三个肌肉记忆键位:d 进 Diff、enter 写评论、shift+r 审批、m 合并。装好之后你只需一条 ghui 命令,就能在终端里完整跑完一个 Pull Request 的审阅闭环。如果它让你少切一次浏览器,那就是赚的。