ghui 实战教程:如何在终端查看 Diff、写行内评论并一键审批合并 Pull Request

原创2026-10-14 16:16:591,821 阅读

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 里每一行都是可评论的,操作路径非常短:

  1. 定位代码行:用 j / k(或 15 j 这类数字前缀)把光标移到想评论的代码行;
  2. 新建评论:按 enter——若该行已有评论线程则打开它并追加回复,否则直接弹出评论输入框(CommentModal.tsx);
  3. 输入内容:多行评论按 shift+enter 换行,enter(或 ctrl+s)保存,esc 取消;
  4. 多行范围评论:先按 v 选中起始行,再用 j / k 延伸范围,按 enter 即可对整段代码发表一条评论(再按 v 可取消选区);
  5. 跳转已有讨论:审阅他人意见时用 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):

  1. 用 j / k(或上下方向键)在三选一里切换:
    • Comment——只留意见不表态
    • Approve——批准该 PR
    • Request changes——要求修改
  2. 按 enter 进入可选的 summary 文本区,输入审批总结(不填直接跳过也可以);
  3. 再按 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. 核心模块速查

想了解实现细节,可以从这几个入口入手:

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 的审阅闭环。如果它让你少切一次浏览器,那就是赚的。

登录后查看全文
ghui