如何配置github-pr-diff-tree让新PR自动显示变更文件树:分步教学
如何配置github-pr-diff-tree让新PR自动显示变更文件树:分步教学
在团队协作中,评审 Pull Request 时很容易忽略变更文件在目录中的位置。GitHub Action github-pr-diff-tree 可以自动在 PR 下发布一条评论,把本次改动以「文件树」的直观形式展示出来:哪些文件新增、删除、修改,各改了多少行,一眼就能看全。本文用 3 个步骤带你完成配置,全程只需几行 YAML。
它解决什么问题?
GitHub 自带的 Code Review 页面能展示代码 diff,但变更文件的目录结构往往被评审者忽略。github-pr-diff-tree 的思路很简单:
- 📂 解析 PR 的完整 diff,提取每个文件的路径
- 🌳 把文件按目录层级渲染成一棵可读的文件树
- 💬 在 PR 里自动创建(或更新)一条
Changed Files Tree评论
每个文件后面还会标注 (M +1, −0) 这类信息,表示修改状态与增删行数,新增文件标 (A)、删除文件标 (D),非常清晰。
第一步:创建 Workflow 文件
在仓库的 .github/workflows/ 目录下新建 pr-diff-tree.yml,内容如下:
# .github/workflows/pr-diff-tree.yml
name: 'PR Diff Tree'
on:
pull_request:
types: [opened, synchronize]
jobs:
dump:
runs-on: ubuntu-latest
steps:
- uses: wadackel/github-pr-diff-tree@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}
几个关键点说明:
- 触发时机:
types: [opened, synchronize]表示 PR 打开和推送新提交时都会触发。如果希望合并前最后一次提交也刷新,可以再加上reopened。 - Action 版本:使用
@v1锁定主版本,避免意外升级。
第二步:确认唯一的必填参数 token
这个 Action 只有一个输入参数 token,用于向 GitHub API 发起请求(获取 diff、写评论)。在 action.yml 中可以确认它的定义:
| 参数 | 必填 | 说明 |
|---|---|---|
token |
✅ | 使用 secrets.GITHUB_TOKEN 即可,无需额外配置 |
💡
GITHUB_TOKEN是 GitHub Actions 自动提供的内置 token,拥有对当前仓库 issue 评论的读写权限,不需要在 Settings 里手动创建任何 token。
如果运行时报 Permission denied,请检查仓库 Settings → Secrets and permissions 中是否勾选了 Issues: read and write 权限。
第三步:验证自动评论效果
提交 workflow 文件后,随便开一个 PR,Actions 页面会出现名为 PR Diff Tree 的运行记录。成功后回到 PR 页面,会看到 github-actions 机器人发出的「Changed Files Tree」评论。
几个实用细节:
- 自动去重更新:Action 内部会用固定标记识别旧评论,PR 每次 push 新提交后是更新同一条评论,而不是刷出一堆重复内容(实现见 src/main.ts 的 upsert 逻辑)。
- 支持的文件类型:解析器 src/parse.ts 能处理新增、删除、修改、重命名文件以及二进制文件,路径中的引号转义也会自动清理。
- 渲染逻辑:文件树由 src/print.ts 生成,输出到 src/types.ts 定义的文件结构中。
工作原理速览
整个流程在 src/main.ts 中串联完成,共 4 步:
- 从事件上下文取到当前 PR 编号
- 通过 GitHub API 拉取该 PR 的完整 diff(
mediaType: diff) parse解析 diff →print渲染成文件树- 在 PR 中 upsert 一条带文件树的评论
如果你想在其他项目里参考这类实现,直接看 README.md 的 Usage 章节和测试用例 tests/parse.test.ts 就能快速上手。
常见问题
Q:为什么没有自动触发?
确认 workflow 文件名放在 .github/workflows/ 下,且仓库不是 fork 后新建的分支触发的 PR(跨 fork PR 会因 token 权限受限而失败)。
Q:评论里缺少某些文件? diff 超过 API 单次返回上限时可能被截断,大型重构建议拆分 PR。
Q:如何取消自动评论?
删除 .github/workflows/pr-diff-tree.yml 即可,已有的历史评论可手动删除。
配置完成后,团队每次评审 PR 都能先扫一眼文件树,快速判断改动范围是否合理——评审效率提升就是这么简单 🌲
