github-pr-diff-tree实战教程:让第一个PR立刻拥有变更文件目录树

原创2026-11-06 15:20:421,844 阅读

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。

github-pr-diff-tree 在 PR 中生成的变更文件目录树效果截图

快速开始:一段 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, -98
  • R old/path —— 重命名文件(Renamed),括号里是原路径
  • 二进制文件只显示 M,不带行数统计

以项目自身的 PR 为例(见上图),一眼就能看出:_tests/ 目录里删了 main.test.ts、加了 print.test.ts,src/ 里三个文件被修改——审查者立刻知道该把精力放在哪里。

工作原理:从 diff 文本到目录树

整个 Action 只有三个核心模块,逻辑清晰,适合顺手学习 GitHub Action 开发:

  1. 拉取 diff:src/main.ts 通过 GitHub API 以 mediaType: diff 获取 PR 的原始 diff 文本;
  2. 解析文件清单:src/parse.ts 逐行解析 diff,识别 added / deleted / modified / renamed 四种变更类型(类型定义见 src/types.ts),并统计每个文件的增删行数、兼容文件名带引号/空格及二进制文件等边界情况;
  3. 构建树形结构: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 都自带"变更地图"吧 🗺️

登录后查看全文
github-pr-diff-tree