This is an automated email from the ASF dual-hosted git repository.
aw pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/yetus.git
The following commit(s) were added to refs/heads/main by this push:
new 82756a2 YETUS-1026. precommit docs lost utilities (#163)
82756a2 is described below
commit 82756a2cdb4ad71dbdf936072920145f03db23b3
Author: Allen Wittenauer <[email protected]>
AuthorDate: Mon Oct 19 07:50:04 2020 -0700
YETUS-1026. precommit docs lost utilities (#163)
Signed-off-by: Sean Busbey <[email protected]>
---
.../in-progress/precommit/index.html.md | 11 ++++
.../precommit/smart-apply-patch.html.md | 59 +++++++++++++++++++++-
precommit/src/main/shell/smart-apply-patch.sh | 4 +-
3 files changed, 71 insertions(+), 3 deletions(-)
diff --git
a/asf-site-src/source/documentation/in-progress/precommit/index.html.md
b/asf-site-src/source/documentation/in-progress/precommit/index.html.md
index 1f40028..ed0f561 100644
--- a/asf-site-src/source/documentation/in-progress/precommit/index.html.md
+++ b/asf-site-src/source/documentation/in-progress/precommit/index.html.md
@@ -28,6 +28,7 @@
* [Plug-ins](#plug-ins)
* [Bundled Plug-ins](#bundled-plug-ins)
* [Optional Plug-ins](#optional-plug-ins)
+* [Related Utilities](#related-utilities)
* [More information](#more-information)
<!-- /MarkdownTOC -->
@@ -149,6 +150,16 @@ Language Support, Licensing, and more:
* [SpotBugs](plugins/spotbugs)
* [yamllint](plugins/yamllint)
+# Related Utilities
+
+`precommit` also comes with some utilities that are useful in various
+capacities without needing to use the full `test-patch` runtime:
+
+* [docker-cleanup](docker-cleanup) - safe removal of Docker resources for
multi-executor CI systems
+* [jenkins-admin](admin) - Jenkins<->JIRA patch bridge
+* [qbt](qbt) - Quality Build Tool, for branch-specific testing
+* [smart-apply-patch](smart-apply-patch) - CLI manipulation and query of patch
files, PRs, and more
+
# More information
* [Usage Introduction](usage-intro)
diff --git
a/asf-site-src/source/documentation/in-progress/precommit/smart-apply-patch.html.md
b/asf-site-src/source/documentation/in-progress/precommit/smart-apply-patch.html.md
index 0ef8b3e..a451928 100644
---
a/asf-site-src/source/documentation/in-progress/precommit/smart-apply-patch.html.md
+++
b/asf-site-src/source/documentation/in-progress/precommit/smart-apply-patch.html.md
@@ -19,9 +19,19 @@
# smart-apply-patch
+<!-- MarkdownTOC levels="1,2,3" autolink="true" indent=" " bullets="*"
bracket="round" -->
+
+* [Local File](#local-file)
+* [Remote Files and Bug Systems](#remote-files-and-bug-systems)
+* [Dry-run](#dry-run)
+* [Committer Mode](#committer-mode)
+* [Patch Reporting](#patch-reporting)
+
+<!-- /MarkdownTOC -->
+
`smart-apply-patch` is a command to help apply patches easily. It uses the
same plug-ins and many of the same options as test-patch. This means that it
can, for example, fetch patches from JIRA and apply them to a local source tree.
-## Usage
+# Local File
Its simplest form is used when a patch is stored in a local file:
@@ -31,12 +41,27 @@ $ smart-apply-patch patch
This will cause the command to run through various ways to verify and then
apply the patch to the current repo, including deducing a patch level.
+# Remote Files and Bug Systems
+
+`smart-apply-patch` supports many of the same switches and configurations
+that `test-patch` does. Using those switches means that, for example, it is
possible to pull and apply a GitHub PR very easily:
+
+```bash
+$ smart-apply-patch --plugins=github --github-repo apache/yetus GH:3000
+```
+
+`smart-apply-patch` will do all the work of downloading, verifying, and
applying just as `test-patch` would.
+
+# Dry-run
+
Perhaps you just want to see if the patch even applies without changing your
local repo. The `--dry-run` option will just test for applicability:
```bash
$ smart-apply-patch --dry-run patch
```
+# Committer Mode
+
For committers of projects, there is a special mode:
```bash
@@ -48,3 +73,35 @@ that in addition to applying the patch will also attempt to:
* use `--whitespace=fix` mode
* add all newly created files in the repo
* use `--signoff` and commit the change via git-am
+
+# Patch Reporting
+
+For speciality CI needs, it may be useful to just have access to Apache Yetus'
+ability to interpret changes and then do your own actions based upon that
+content. `smart-apply-patch` has two options that expose that functionality
+for highly customized CI needs:
+
+```bash
+$ smart-apply-patch --plugins=gitlab --changedfilesreport=/tmp/myfile.txt
GL:100
+```
+
+This command will download GitLab merge request #100, process it, and write a
+file called `/tmp/myfile.txt` that lists the files that were changed.
+
+```bash
+$ smart-apply-patch --build-tool=maven --plugins=maven
--changedmodulesreport=/tmp/mymodules.txt /tmp/file.patch
+```
+
+Similarly, this option will return the module list from `/tmp/file.patch`.
+Or, perhaps you simply want to know the deepest directory with a change?
+
+```bash
+$ smart-apply-patch --build-tool=maven --plugins=maven
--changedunionreport=/tmp/base.txt http://example.com/patch
+```
+
+If you want to generate these reports without actually applying it (where
+possible), then the `--reports-only` option is available:
+
+```bash
+$ smart-apply-patch --reports-only --changedfilesreport=/tmp/myfile.txt
/tmp/file.patch
+```
diff --git a/precommit/src/main/shell/smart-apply-patch.sh
b/precommit/src/main/shell/smart-apply-patch.sh
index a918c16..ede728e 100755
--- a/precommit/src/main/shell/smart-apply-patch.sh
+++ b/precommit/src/main/shell/smart-apply-patch.sh
@@ -120,6 +120,7 @@ function yetus_usage
yetus_add_option "--committer" "Apply patches like a boss."
yetus_add_option "--debug" "If set, then output some extra stuff to stderr"
yetus_add_option "--dry-run" "Check for patch viability without applying"
+ yetus_add_option "--gpg-sign" "GPG sign the commit using gpg keys"
yetus_add_option "--ignore-unknown-options=<bool>" "Continue despite unknown
options (default: ${IGNORE_UNKNOWN_OPTIONS})"
yetus_add_option "--list-plugins" "List all installed plug-ins and then exit"
yetus_add_option "--modulelist=<list>" "Specify additional modules to test
(comma delimited)"
@@ -131,7 +132,6 @@ function yetus_usage
yetus_add_option "--skip-system-plugins" "Do not load plugins from
${BINDIR}/test-patch.d"
yetus_add_option "--user-plugins=<dir>" "A directory of user provided
plugins. see test-patch.d for examples (default empty)"
yetus_add_option "--version" "Print release version information and exit"
- yetus_add_option "--gpg-sign" "GPG sign the commit using gpg keys"
yetus_generic_columnprinter "${YETUS_OPTION_USAGE[@]}"
yetus_reset_usage
@@ -150,11 +150,11 @@ function yetus_usage
echo ""
echo "Patch reporting:"
- yetus_add_option "--report-only" "Do not try to apply at all; just report on
the patch"
yetus_add_option "--build-tool=<tool>" "Override the build tool"
yetus_add_option "--changedfilesreport=<name>" "List of files that this
patch modifies"
yetus_add_option "--changedmodulesreport=<name>" "List of modules that this
patch modifies"
yetus_add_option "--changedunionreport=<name>" "Union of modules that this
patch modifies"
+ yetus_add_option "--report-only" "Do not try to apply at all; just report on
the patch"
yetus_generic_columnprinter "${YETUS_OPTION_USAGE[@]}"
yetus_reset_usage
