Apache Yetus 常用 CLI 命令与工具详解
整理 Apache Yetus 0.15.1 内置命令行工具用法，覆盖 releasedocmaker、test-patch、shelldocs、smart-apply-patch、qbt 的帮助原文、真实执行示例、输出解读与工具选型建议。
Apache YetusApache Yetus2026/10/12
Apache Yetus 常用 CLI 命令与工具详解
一、工具总览
Apache Yetus 0.15.1 官方二进制包解压后，bin 目录实测包含以下命令：
| 命令 | 用途 |
|---|---|
| releasedocmaker | 从 JIRA 生成 CHANGELOG 与 RELEASENOTES 发布文档 |
| test-patch | 补丁/PR 预提交审计，按插件执行静态检查与构建测试 |
| smart-apply-patch | 智能应用补丁（自动识别基线分支，支持干跑） |
| shelldocs | 解析 shell 函数的注释标注，生成 API 文档或做 lint |
| qbt（Queue Build Tool） | 面向 CI 队列的批量预提交驱动器，参数体系与 test-patch 同构 |
| unit-test-filter-file | 单元测试过滤文件辅助工具 |
| jenkins-admin / buildkite-recovery / github-status-recovery | 面向 CI 运维的恢复与治理辅助脚本 |
参数细节的完整说明见《Apache Yetus 配置参数详解》，本篇聚焦每个工具的帮助原文与真实执行示例。
二、releasedocmaker
2.1 帮助全文
releasedocmaker --help 实测回显：
usage: releasedocmaker [-h] [--dirversions] [--empty] [--extension EXTENSION]
[--fileversions] [-i] [-l] [-p PROJECT] [--prettyindex]
[-r] [--sortorder TYPE] [--sorttype TYPE] [-t TITLE]
[-u] [-v VERSION] [-V] [-O OUTPUT_DIRECTORY]
[-B BASE_URL] [--retries RETRIES] [--skip-credits]
[-X INCOMPATIBLE_LABEL] [-n LINT]
options:
-h, --help show this help message and exit
--dirversions Put files in versioned directories
--empty Create empty files when no issues
--extension EXTENSION
Set the file extension of created Markdown files
--fileversions Write files with embedded versions
-i, --index build an index file
-l, --license Add an ASF license
-p PROJECT, --project PROJECT
projects in JIRA to include in releasenotes
--prettyindex build an index file with pretty URLs
-r, --range Given versions are a range
--sortorder TYPE Sorting order for sort type (default: older)
--sorttype TYPE Sorting type for issues (default: resolutiondate)
-t TITLE, --projecttitle TITLE
Title to use for the project (default is Apache
PROJECT)
-u, --usetoday use current date for unreleased versions
-v VERSION, --version VERSION
versions in JIRA to include in releasenotes
-V display version information for releasedocmaker and
exit.
-O OUTPUT_DIRECTORY, --outputdir OUTPUT_DIRECTORY
specify output directory to put release docs to.
-B BASE_URL, --baseurl BASE_URL
specify base URL of the JIRA instance.
--retries RETRIES Specify how many times to retry connection for each
URL.
--skip-credits While creating release notes skip the 'reporter' and
'contributor' columns
-X INCOMPATIBLE_LABEL, --incompatiblelabel INCOMPATIBLE_LABEL
Specify the label to indicate backward
incompatibility.
-n LINT, --lint LINT Specify lint filters. Valid filters are
'incompatible', 'important', 'version', 'component',
'assignee'. 'all' enables all lint filters. Multiple
filters can be specified comma-delimited and filters
can be negated, e.g. 'all,-component'.
--project and --version may be given multiple times.
2.2 实际执行示例
版本确认：
releasedocmaker -V
实测回显：
0.15.1
对 Apache JIRA 上真实存在的 YETUS 项目生成 0.15.1 发布文档：
releasedocmaker --project YETUS --version 0.15.1 \
--outputdir /tmp/rdm-yetus \
--projecttitle 'Apache Yetus' --index
实测生成 CHANGELOG.md、RELEASENOTES.md、README.md、index.md 四个文件，其中 CHANGELOG.md 内容形如：
# Apache Yetus Changelog
## Release 0.15.1 - 2025-02-16
### BUG FIXES:
| JIRA | Summary | Priority | Component | Reporter | Contributor |
|:---- |:---- | :--- |:---- |:---- |:---- |
| [YETUS-1249](https://issues.apache.org/jira/browse/YETUS-1249) | fix macos tests in yetus-homebrew | Major | homebrew | Allen Wittenauer | Allen Wittenauer |
### OTHER:
| JIRA | Summary | Priority | Component | Reporter | Contributor |
|:---- |:---- | :--- |:---- |:---- |:---- |
| [YETUS-1247](https://issues.apache.org/jira/browse/YETUS-1247) | Update dependencies for 2024-10 | Major | build, github-action | Allen Wittenauer | Allen Wittenauer |
RELEASENOTES.md 内容形如：
# Apache Yetus 0.15.1 Release Notes
These release notes cover new developer and user-facing incompatibilities, important issues, features, and major improvements.
---
* [YETUS-1247](https://issues.apache.org/jira/browse/YETUS-1247) | *Major* | **Update dependencies for 2024-10**
2.3 典型报错与处理
项目不存在时实测报错：
JIRA returns HTTP error 400: . Aborting.
- Please ensure that specified authentication, projects, fixVersions etc. are correct.
- The value 'DEMOSHELL' does not exist for the field 'project'.
处理：改用真实存在的 JIRA 项目名与版本号。
多版本未指定命名方式时实测报错：
releasedocmaker: error: Multiple versions require either --fileversions or --dirversions
处理：追加 --fileversions 或 --dirversions。
三、test-patch
3.1 帮助全文
test-patch --help 实测回显（与隔离运行环境相关的高级参数请查阅官方文档，此处不展开）：
test-patch [OPTIONS] patch
Where:
patch is a file, URL, or bugsystem-compatible location of the patch file
Options:
--archive-list=<list> Comma delimited list of pattern matching
notations to copy to patch-dir
--basedir=<dir> The directory to apply the patch to
(default: current directory)
--branch-default=<ref> If the branch isn't forced and we don't
detect one in the patch name, use this
branch (default 'main')
--branch=<ref> Forcibly set the branch
--bugcomments=<bug> Only write comments to the screen and this
comma delimited list (default: 'None: no
plugins enabled')
--build-native=<bool> If true, then build native components
(default 'true')
--build-tool=<tool> Pick which build tool to focus around
(default: autodetect from 'nobuild')
--continuous-improvement=<bool> If true, then do not exit with failure on
branches (default: false)
--contrib-guide=<url> URL to point new users towards project
conventions. (default:
https://yetus.apache.org/documentation/in-pr
ogress/precommit-patchnames )
--debug If set, then output some extra stuff to
stderr
--dirty-workspace Allow the local git workspace to have
uncommitted changes
--empty-patch Create a summary of the current source tree
--excludes=<file> File of regexs to keep project files out of
the set of changes passed to plugins.
--git-offline Do not fail if git cannot do certain remote
operations
--git-shallow Repo does not know about other branches or
tags
--ignore-unknown-options=<bool> Continue despite unknown options (default:
false)
--java-home=<path> Set JAVA_HOME
--linecomments=<bug> Only write line comments to this comma
delimited list (default: same as
--bugcomments)
--list-plugins List all installed plug-ins and then exit
--modulelist=<list> Specify additional modules to test (comma
delimited)
--multijdkdirs=<paths> Comma delimited lists of JDK paths to use
for multi-JDK tests
--multijdktests=<list> Comma delimited tests to use when
multijdkdirs is used. (default:
'compile,unit,javadoc')
--offline Avoid connecting to the network
--patch-dir=<dir> The directory for working and output files
(default '/tmp/test-patch-unknown/pid')
--personality=<file> The personality file to load
--plugins=<list> Specify which plug-ins to add/delete (comma
delimited; use 'all' for all found) e.g.
--plugins=all,-ant,-scalac (all plugins
except ant and scalac)
--proclimit=<num> Limit on the number of processes (default:
2000)
--project=<name> The short name for project currently using
test-patch (default 'yetus')
--report-unknown-options=<bool> Print a warning in the report if
--ignore-unknown-options=true and unknown
options were found (default: true)
--resetrepo Forcibly clean the repo
--run-tests Run all relevant tests below the base
directory
--skip-dirs=<list> Skip following directories for module
finding
--skip-system-plugins Do not load plugins from
/opt/yetus/lib/precommit/plugins.d
--summarize=<bool> Allow tests to summarize results
--test-parallel=<bool> Run multiple tests in parallel (default
false in developer mode, true in Jenkins
mode)
--test-threads=<int> Number of tests to run in parallel (default
defined in unknown build)
--tests-filter=<list> Lists of tests to turn failures into
warnings
--unit-test-filter-file=<file> The unit test filter file to load
--user-plugins=<dir> A directory of user provided plugins.
(default: )
--version Print release version information and exit
Shell binary overrides:
--awk-cmd=<cmd> The 'awk' command to use (default 'awk')
--curl-cmd=<cmd> The 'curl' command to use (default 'curl')
--diff-cmd=<cmd> The GNU-compatible 'diff' command to use (default 'diff')
--file-cmd=<cmd> The 'file' command to use (default 'file')
--git-cmd=<cmd> The 'git' command to use (default 'git')
--grep-cmd=<cmd> The 'grep' command to use (default 'grep')
--patch-cmd=<cmd> The 'patch' command to use (default 'patch')
--sed-cmd=<cmd> The 'sed' command to use (default 'sed')
Automation options:
--build-url-artifacts=<location> Location relative to --build-url of the
--patch-dir (Default:
'artifact/patchprocess')
--build-url-console=<location> Location relative to --build-url of the
console (Default: 'console')
--build-url=<url> Set the build location web page (Default:
'')
--console-report-file=<file> Save the final console-based report to a
file in addition to the screen
--console-urls Use the build URL instead of path on the
console report
--instance=<string> Parallel execution identifier string
--mv-patch-dir Move the patch-dir into the basedir during
cleanup
--robot Assume this is an automated run (default:
auto-detect supported CI system)
--sentinel A very aggressive robot (auto: --robot)
3.2 实际执行示例
查看可用插件：
test-patch --list-plugins
实测回显：
Reminder: every plug-in may be enabled via 'all'.
BUILDTOOLS:
nobuild ant autoconf cmake gradle make maven
TESTTYPES:
ansiblelint asflicense author blanks buf buflint bufcompat cc checkmake checkstyle codespell detsecrets dupname golang golangcilint hadolint javac javadoc jshint jsonlint markdownlint mvnsite pathlen perlcritic pylint revive rubocop scalac scaladoc shellcheck shelldocs spotbugs test4tests unitveto xmllint yamllint
BUGSYSTEMS:
briefreport bugzilla csvout github gitlab htmlout jira junit slack
TESTFORMATS:
ctest junit tap
对纯 shell 项目的补丁执行最小审计（实测通过）：
test-patch --project=demo \
--basedir=/opt/demo-shell \
--patch-dir=/tmp/tp-out \
--plugins=shellcheck,shelldocs,blanks,test4tests \
--build-tool=nobuild \
--offline \
/tmp/demo.patch
实测报告（节选）：
-1 overall
| Vote | Subsystem | Runtime | Comment
============================================================================
| +1 | blanks | 0m 0s | The patch has no blanks issues.
| -1 | shellcheck | 0m 1s | The patch generated 1 new + 0 unchanged
| | | | - 0 fixed = 1 total (was 0)
| +1 | shelldocs | 0m 0s | No new issues.
|| Subsystem || Report/Notes ||
| shellcheck | /tmp/tp-out/results-shellcheck.txt |
| Optional Tests | shellcheck shelldocs |
| Build tool | nobuild |
| versions | git=2.34.1 shellcheck=0.8.0 |
| Powered by | Apache Yetus 0.15.1 https://yetus.apache.org |
明细结果文件 results-shellcheck.txt 实测内容：
build.sh:6:4: note: Double quote to prevent globbing and word splitting. [SC2086]
整体投票为 -1 时进程退出码为 1；全部通过时为 0。
3.3 典型报错与处理
工作区不干净时实测报错：
ERROR: --dirty-workspace option not provided.
ERROR: can't run in a workspace that contains the following modifications
M build.sh
处理：还原或提交修改，或追加 --dirty-workspace。
补丁无法应用时实测报告：
| -1 | patch | 0m 0s | /tmp/demo.patch does not apply to
| | | | feature/patch. Rebase required? Wrong
| | | | Branch? See
| | | | https://yetus.apache.org/documentation/in-pr
| | | | ogress/precommit-patchnames for help.
处理：切回补丁基线分支后重跑，或用 --branch/--branch-default 指定目标分支。
四、shelldocs
4.1 帮助全文
shelldocs --help 实测回显：
usage: shelldocs [-h] [-o OUTFILE] [-i INFILE] [--skipprnorep] [--lint] [-V]
options:
-h, --help show this help message and exit
-o OUTFILE, --output OUTFILE
file to create
-i INFILE, --input INFILE
file to read
--skipprnorep Skip Private & Not Replaceable
--lint Enable lint mode
-V, --version display version information for shelldocs and exit.
You can mark a file to be ignored by shelldocs by adding 'SHELLDOC-IGNORE' as
comment in its own line. --input may be given multiple times.
4.2 注释标注格式
shelldocs 只识别双井号（##）的函数注释标注，支持的关键字包括 @description、@audience、@stability、@replaceable、@param、@return 等。实测示例文件：
cat > /tmp/funcs2.sh <<'EOF'
## @description build the project
## @audience private
## @stability stable
function buildit { echo ok; }
EOF
lint 模式检查（标注缺失时报告错误；单井号注释不会被识别为有效标注）：
shelldocs --input /tmp/funcs2.sh --lint
echo "lint exit: $?"
实测回显（标注齐全时无输出）：
lint exit: 0
标注缺失时的实测回显：
/tmp/funcs.sh:4:ERROR: function buildit has no @audience
/tmp/funcs.sh:4:ERROR: function buildit has no @stability
注意：即便报 ERROR，lint 模式进程退出码实测仍为 0，流水线卡点不能依赖其退出码，需解析输出。
4.3 生成 API 文档
shelldocs --input /tmp/funcs2.sh --output /tmp/funcs-doc.md
cat /tmp/funcs-doc.md
实测输出（含 ASF 许可声明头，节选主体）：
* Private/Stable/Not Replaceable
* [buildit](#buildit)
------
## Private/Stable/Not Replaceable
### `buildit`
* Synopsis
```
buildit
```
* Description
build the project
* Returns
Nothing
| Classification | Level |
| :--- | :--- |
| Audience | Private |
| Stability | Stable |
| Replaceable | False |
五、smart-apply-patch
5.1 帮助全文
smart-apply-patch --help 实测回显：
smart-apply-patch.sh [OPTIONS] patch
Where:
patch is a file, URL, or bugsystem-compatible location of the patch file
Options:
--committer Apply patches like a boss.
--debug If set, then output some extra stuff to
stderr
--dry-run Check for patch viability without applying
--gpg-sign GPG sign the commit using gpg keys
--ignore-unknown-options=<bool> Continue despite unknown options (default:
false)
--list-plugins List all installed plug-ins and then exit
--modulelist=<list> Specify additional modules to test (comma
delimited)
--offline Avoid connecting to the Internet
--patch-dir=<dir> The directory for working and output files
(default '/tmp/yetus-(random))
--personality=<file> The personality file to load
--plugins=<list> Specify which plug-ins to add/delete (comma
delimited; use 'all' for all found)
--project=<name> The short name for project currently using
test-patch (default 'yetus')
--skip-system-plugins Do not load plugins from
/opt/yetus/lib/precommit/plugins.d
--user-plugins=<dir> A directory of user provided plugins.
(default )
--version Print release version information and exit
Shell binary overrides:
--awk-cmd=<cmd> The 'awk' command to use (default 'awk')
--curl-cmd=<cmd> The 'curl' command to use (default 'curl')
--diff-cmd=<cmd> The GNU-compatible 'diff' command to use (default 'diff')
--file-cmd=<cmd> The 'file' command to use (default 'file')
--git-cmd=<cmd> The 'git' command to use (default 'git')
--grep-cmd=<cmd> The 'grep' command to use (default 'grep')
--patch-cmd=<cmd> The 'patch' command to use (default 'patch')
--sed-cmd=<cmd> The 'sed' command to use (default 'sed')
5.2 实际执行示例
干跑校验补丁可应用性（不实际修改文件）：
cd /opt/demo-shell
smart-apply-patch --project=demo --patch-dir=/tmp/sap-out --dry-run /tmp/demo.patch
实测回显：
Processing: /tmp/demo.patch
Patch file /tmp/demo.patch copied to /tmp/sap-out
去掉 --dry-run 后即为真实应用补丁；--committer 模式会以提交方式落盘，--gpg-sign 可对提交签名。
六、qbt（Queue Build Tool）
6.1 用途与帮助
qbt 面向 CI 队列场景批量驱动预提交任务，参数体系与 test-patch 同构（--basedir、--patch-dir、--plugins、--build-tool、--personality、--offline、自动化参数等完全一致）。qbt --help 实测开头：
qbt [OPTIONS] patch
Where:
patch is a file, URL, or bugsystem-compatible location of the patch file
Options:
--archive-list=<list> Comma delimited list of pattern matching
notations to copy to patch-dir
--basedir=<dir> The directory to apply the patch to
(default: current directory)
--branch-default=<ref> If the branch isn't forced and we don't
detect one in the patch name, use this
branch (default 'main')
（后续选项与 test-patch 相同，完整清单见《Apache Yetus 配置参数详解》。）
6.2 使用要点
- qbt 与 test-patch 共享同一套插件体系与 personality 机制，可在 CI 上以队列方式并行审计多个补丁；
- 开发者本地日常审计用 test-patch 即可，qbt 主要服务于集中式 CI 节点。
七、其他辅助工具
- unit-test-filter-file：生成/维护单元测试过滤文件，配合 test-patch 的 --unit-test-filter-file 参数使用；
- jenkins-admin、buildkite-recovery、github-status-recovery：面向 Jenkins、Buildkite、GitHub 状态的恢复与治理脚本，供 CI 平台管理员使用；
- 以上工具在 bin 目录均有可执行入口，用 --help 查看各自参数。
八、工具选型建议
| 场景 | 推荐工具 |
|---|---|
| 发布前生成 CHANGELOG / RELEASENOTES | releasedocmaker |
| 补丁/PR 合入前质量审计 | test-patch |
| 校验补丁能否干净应用 | smart-apply-patch --dry-run |
| shell 函数库 API 文档与标注检查 | shelldocs |
| CI 集中节点批量审计 | qbt |
九、常见问题
Q1： 运行任何工具报 "command not found"？
定位：PATH 未包含 $YETUS_HOME/bin。解决：确认 /etc/profile.d/yetus.sh 存在且包含 export PATH=$YETUS_HOME/bin:$PATH，重新登录或 source 后重试。
Q2： test-patch 报告中 Optional Tests 为空？
定位：默认不启用任何插件。解决：显式传 --plugins，如 --plugins=shellcheck,shelldocs,blanks。
Q3： shelldocs --lint 报 ERROR 但退出码为 0？
定位：0.15.1 实测 lint 模式不把错误反映到退出码。解决：流水线中解析输出文本判断是否存在 ERROR 行。
Q4： releasedocmaker 报 HTTP 400？
定位：--project 或 --version 在目标 JIRA 上不存在。解决：核对项目名与 fixVersions 后重试，自建 JIRA 用 --baseurl 指定实例地址。
十、参考链接
- Apache Yetus 官方文档首页：https://yetus.apache.org/
- releasedocmaker 官方文档：https://yetus.apache.org/documentation/in-progress/releasedocmaker
- test-patch 官方文档：https://yetus.apache.org/documentation/in-progress/precommit/
- smart-apply-patch 官方文档：https://yetus.apache.org/documentation/in-progress/smart-apply-patch
- shelldocs 官方文档：https://yetus.apache.org/documentation/in-progress/shelldocs
- GitHub 仓库：https://github.com/apache/yetus
章节目录