HDDS-13755. Add doc for ozone sh snapshot listDiff command

[rich7420]

What changes were proposed in this pull request?

follow the requirements from this issue:

1. demonstrate --all-status option.
2. clarify the difference between -all-status and -all, the latter tunes pagination limit, not snapdiff job status

I noticed dataflow in this part is like:

CLI Command
  ↓
ListSnapshotDiffHandler.execute()
  ↓ Parse Options:
    • --all-status → listAllStatus (boolean)
    • --job-status → jobStatus (String, default: "in_progress")
    • listOptions.getStartItem() → prevSnapshotDiffJob
    • listOptions.getLimit() → limit (used later for output)
  ↓
ObjectStore.listSnapshotDiffJobs()
  ↓ Creates SnapshotDiffJobIterator
  ↓ When iterator needs data → RPC Call:
    in [Client] part RpcClient → OzoneManagerProtocolClientSideTranslatorPB
      → Builds Protobuf Request (ListSnapshotDiffJobRequest)
      → OmTransport.submitRequest() (gRPC/Hadoop RPC)
    in [Network] part gRPC/Protobuf RPC transmission
    in [Server] part OzoneManagerProtocolServerSideTranslatorPB
      → OzoneManagerRequestHandler
      → OzoneManager.listSnapshotDiffJobs() (ACL checks, metrics)
      → OmSnapshotManager.getSnapshotDiffList() (validation)
      → SnapshotDiffManager.getSnapshotDiffJobList()
        • Filters by volumeName, bucketName
        • Filters by status (if listAllStatus=true: all jobs, else: match jobStatus)
        • Limits by maxEntries (server-side pagination)
        • Returns ListSnapshotDiffJobResponse
  ↓
Response flows back → SnapshotDiffJobIterator
  ↓ Converts to Iterator<OzoneSnapshotDiff> and Stores continuation token for next page
  ↓
printAsJsonArray(iterator, limit)

What is the link to the Apache JIRA

HDDS-13755

How was this patch tested?

none

[Copilot]

Pull Request Overview

This PR enhances the snapshot documentation by adding detailed usage instructions for the listDiff command. The update provides comprehensive guidance on filtering snapshot diff jobs by status and clarifies the distinction between status filtering and pagination options.

Key Changes

• Added documentation for the listDiff command with multiple usage examples
• Documented the --job-status and --all-status flags for filtering snapshot diff jobs
• Clarified the difference between --all-status (status filtering) and -all/-a (pagination) options

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[rich7420]

I'm not sure if this is the right place to put the section. plz feel free to correct me!

[jojochuang]

-l defaults to 100:

ozone/hadoop-ozone/cli-shell/src/main/java/org/apache/hadoop/ozone/shell/ListLimitOptions.java

Line 47 in 584ebb9

defaultValue = "100",

[jojochuang]

I'm fine to not mention it since it's too detailed. The pagination limit default is also applicable to other commands so mentioning it here isn't appropriate.

[rich7420]

@jojochuang thanks for the feedback!

[jojochuang]

LGTM

[rich7420]

@jojochuang thanks a lot!