github-pr-diff-tree实战教程:让第一个PR立刻拥有变更文件目录树
github-pr-diff-tree实战教程:让第一个PR立刻拥有变更文件目录树
如果你经常审查或提交 Pull Request,一定被密密麻麻的 diff 列表淹没过。github-pr-diff-tree 是一个轻量的 GitHub Action,它会在 PR 下自动评论一份变更文件目录树(Changed Files Tree):新增、删除、修改、重命名一目了然,还附带每个文件的增删行数。接入只需一段 YAML 配置,几分钟就能让代码审查效率翻倍 🌲
为什么需要 PR 变更文件目录树
GitHub 的 PR 审查页面虽然强大,但只能按顺序平铺展示每个文件的 diff。当一个 PR 涉及几十个文件时,审查者很难回答两个问题:
- 这个 PR 到底动了哪些目录?
- 哪些是新增/删除,哪些只是小修小补?
github-pr-diff-tree 的设计目标正是补上这个盲区——把 diff 的目录结构以人类可读的树形格式可视化,让审查者 3 秒内抓住 PR 的全貌,从而提升审查准确性。项目动机详见 README.md。
快速开始:一段 YAML 接入 PR 目录树 Action
接入非常简单,只需要在仓库中创建一个 workflow 文件 .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 }}
关键点说明:
| 配置项 | 说明 |
|---|---|
on: pull_request |
监听 PR 事件,opened 和 synchronize 保证首次提交与每次 push 都会刷新目录树 |
token |
唯一必填参数,使用 GitHub 自动注入的 GITHUB_TOKEN 即可,无需额外权限配置 |
| 触发方式 | 基于注释指纹识别,重复触发时更新原评论而非刷屏,PR 下始终只有一条目录树 |
Action 的入参定义见 action.yml,当前仅 token 一个必填项,零学习成本。
效果解析:读懂目录树中的 4 种文件标记
生成的目录树借鉴了 git status 的标记风格,每行文件后的括号就是"变更摘要":
A—— 新增文件(Added),行首带+D—— 删除文件(Deleted),行首带-M +N, -N—— 修改文件(Modified),并直接标出新增/删除的行数,如M +18, -98R old/path—— 重命名文件(Renamed),括号里是原路径- 二进制文件只显示
M,不带行数统计
以项目自身的 PR 为例(见上图),一眼就能看出:_tests/ 目录里删了 main.test.ts、加了 print.test.ts,src/ 里三个文件被修改——审查者立刻知道该把精力放在哪里。
工作原理:从 diff 文本到目录树
整个 Action 只有三个核心模块,逻辑清晰,适合顺手学习 GitHub Action 开发:
- 拉取 diff:src/main.ts 通过 GitHub API 以
mediaType: diff获取 PR 的原始 diff 文本; - 解析文件清单:src/parse.ts 逐行解析 diff,识别
added / deleted / modified / renamed四种变更类型(类型定义见 src/types.ts),并统计每个文件的增删行数、兼容文件名带引号/空格及二进制文件等边界情况; - 构建树形结构:src/print.ts 把扁平的文件列表按路径分组,递归生成目录树,再用
├──、└──渲染出最终文本(渲染逻辑见 src/print.ts)。
两个解析函数都有完整的单元测试覆盖:tests/parse.test.ts 和 tests/print.test.ts。如果你想本地验证,运行 npm test 即可执行完整测试套件。
总结:适合什么样的团队
- ✅ 审查效率敏感的团队:大 PR 一眼看清改动范围,减少来回沟通
- ✅ 新手第一次提交 PR:目录树帮助评审快速定位重点,PR 体验更好
- ✅ 想学习 GitHub Action 的团队:代码量小、结构清晰(约 300 行 TypeScript),是很好的入门读物
github-pr-diff-tree 采用 MIT 协议,配置一行、收益立现。把它加进你的 workflow,让每一个 PR 都自带"变更地图"吧 🗺️
