rangareddy opened a new pull request, #19799: URL: https://github.com/apache/hudi/pull/19799
### Describe the issue this Pull Request addresses Closes part of #15376 (JIRA: [HUDI-4689](https://issues.apache.org/jira/browse/HUDI-4689), epic [HUDI-1388](https://issues.apache.org/jira/browse/HUDI-1388)), which asks for documentation covering all CLI commands. `hudi-cli` on `master` exposes **106 commands across 26 command classes**. `website/docs/cli.md` covered 86 of them. The 20 that were missing entirely: | Command class | Undocumented commands | | --- | --- | | `LockAuditingCommand` | `locks audit enable` / `disable` / `status` / `validate` / `cleanup` | | `TimelineCommand` | `timeline show active` / `show incomplete`, `metadata timeline show active` / `show incomplete` | | `RepairsCommand` | `rename partition`, `repair deprecated partition`, `repair show empty commit metadata` | | `DiffCommand` | `diff file`, `diff partition` | | `RestoresCommand` | `show restore`, `show restores` | | `ArchivedCommitsCommand` | `trigger archival` | | `KerberosAuthenticationCommand` | `kerberos kdestroy` | | `MetadataCommand` | `metadata delete-record-index` | | `TableCommand` | `table set-meta-fields-mode` | The `help` output embedded in the page had drifted too, so a reader could not even discover those commands existed from the docs. ### Summary and Changelog One file, `website/docs/cli.md`. - **The `help` listing now carries all 106 commands.** Entries were inserted at their alphabetical positions rather than the block being regenerated, so the diff stays reviewable. - **Five new reference sections**, each giving the command's purpose, its options and their defaults: - `Auditing Storage Locks` — the five `locks audit` commands, the on-disk layout (`<basePath>/.hoodie/.locks/audit_enabled.json` for the config, `<basePath>/.hoodie/.locks/audit/` for the JSONL records), and what `validate` treats as an error (overlapping transaction windows) versus a warning (a transaction that never released its lock). - `Inspecting the Timeline` — the four timeline commands, their output columns, and which options apply to which. - `Diffing a File or Partition` — `diff file` and `diff partition`. - `Repairing a Table` — `rename partition`, `repair deprecated partition`, `repair show empty commit metadata`. - `Changing the Meta Fields Mode` — `table set-meta-fields-mode` and its two guards. - **Four more folded into the sections they belong to**: `trigger archival` under Archived Commits, `show restore` / `show restores` under Savepoint and Restore, `kerberos kdestroy` under the Kerberos section, `metadata delete-record-index` under Record Index Lookup. Every option name, default and behaviour was read from the command classes on `master`, not from the help text alone. That matters, because in three places the two disagree or the help text is silent: - **`diff file` and `diff partition` ignore `--startTs` and `--endTs` unless `--includeArchivedTimeline` is also `true`.** `CLIUtils#getTimelineInRange` (`:46-62`) applies the bounds only on the archived branch and returns the whole active timeline otherwise, so a narrow range silently does nothing. The help text advertises the defaults with no hint of the precondition. Documented explicitly. - **`repair show empty commit metadata` returns `void`** and reports through `log.warn`, so it renders no result table; the findings land in the CLI log. Documented, rather than implying it prints a result. - **`rename partition` physically removes the old partition directory** after its `delete_partition` write (`SparkMain#renamePartition`), while `repair deprecated partition` leaves the emptied `default` directory in place. The two are otherwise the same shape, so the difference is easy to miss. ### Verification ``` cd website && npm run build -> [SUCCESS] Generated static files in "build" docs markdown link-format checks (the ones asf-site.ci.yml runs on website/docs/**) -> no absolute /docs/ paths, no links missing .md, no ../ or ./ prefixes coverage recheck, parsing @ShellMethod keys out of hudi-cli on master and grepping cli.md -> 106 source commands, 0 missing from cli.md -> 20/20 target commands documented beyond the help listing ``` The five new sections were confirmed present in the rendered `build/docs/next/cli/index.html`. ### Impact Docs only; no code or config changes. The page is the current (`next`) version, so it tracks `master`, which is where these commands live. Versioned copies under `website/versioned_docs/` are deliberately untouched, since several of these commands do not exist in those releases. **This does not close HUDI-4689.** 56 of the 106 commands are still listing-only entries with no prose section. All of them predate this change; this PR closes the gap for the 20 that had no documentation at all. Happy to keep chipping at the remainder in follow-ups if that is the preferred shape, or to fold more in here. ### Risk Level none ### Documentation Update This is the documentation update. ### Contributor's checklist - [x] Read through [contributor's guide](https://hudi.apache.org/contribute/how-to-contribute) - [x] Enough context is provided in the sections above - [x] Adequate tests were added if applicable - [x] CI passes on my PR -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
