Skip to content

Re-order and sync zpool status command usage between CLI help and man page #17357

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
wants to merge 3 commits into from
Closed

Re-order and sync zpool status command usage between CLI help and man page #17357

wants to merge 3 commits into from

Conversation

cmharr
Copy link
Contributor

@cmharr cmharr commented May 20, 2025

Motivation and Context

Addresses inconsistencies in command usage syntax noted in associated Git issue.

#16004

Description

Re-formatted and reordered the usage statement printed by zpool status and then modified the associated man page as well, so the synopsis and description sections match.

How Has This Been Tested?

New usage output:

[root@ironi:zfs]# zpool status -h
invalid option 'h'
usage:
	status [-c [script1[,...]] [-dDegiLpPstvx] ...
	    [-j [--json-int] [--json-flat-vdevs] [--json-pool-key-guid]] ...
	    [--power] [-T d|u] [pool] [interval [count]]

New man page Synopsis:

[root@ironi:zfs]# zpool help status |head -n10
ZPOOL-STATUS(8)               BSD System Manager's Manual               ZPOOL-STATUS(8)

NAME
     zpool-status — show detailed health status for ZFS storage pools

SYNOPSIS
     zpool status [-c script1[,script2,…]] [-dDegiLpPstvx] [-j [--json-int]
           [--json-flat-vdevs] [--json-pool-key-guid]] [--power] [-T d|u] [pool]
           [interval [count]]

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Performance enhancement (non-breaking change which improves efficiency)
  • Code cleanup (non-breaking change which makes code smaller or more readable)
  • Quality assurance (non-breaking change which makes the code more robust against bugs)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Library ABI change (libzfs, libzfs_core, libnvpair, libuutil and libzfsbootenv)
  • [ X] Documentation (a change to man pages or other documentation)

Checklist:

@cmharr cmharr mentioned this pull request May 20, 2025
Closed
@cmharr cmharr force-pushed the zpool_status_sync_docs branch from 692d193 to 49a59f3 Compare May 20, 2025 17:22
@cmharr
Reformat cli help and man page to be in sync
05f4940 
The man page and CLI usage statements were both a little out
of sync and neither fully alphabetized correctly. That has
been fixed. One outstanding question is whether to get rid of
the ellipses on the CLI usage.

Signed-off-by: Cameron Harr <[email protected]>
@cmharr cmharr force-pushed the zpool_status_sync_docs branch from 49a59f3 to 05f4940 Compare May 20, 2025 17:48
behlendorf
behlendorf reviewed May 20, 2025
View reviewed changes
@behlendorf behlendorf added the Status: Code Review Needed Ready for review and testing label May 20, 2025
@cmharr
Refactor man page and CLI help output per mandoc
5e78d58 
The man page and the usage statement from the CLI have been refactored
to abide by the ManDoc standard. Style changes include:
 * Upper-case letters before lower-case
 * List short options w/o arguments first
 * Then list short options w/ arguments
 * Then list long arguments

Signed-off-by: Cameron Harr <[email protected]>
@behlendorf behlendorf added Status: Accepted Ready to integrate (reviewed, tested) and removed Status: Code Review Needed Ready for review and testing labels May 23, 2025
behlendorf pushed a commit that referenced this pull request May 23, 2025
@cmharr @behlendorf
Refactor man page and CLI help output per mandoc
92157c8 
The man page and the usage statement from the CLI have been refactored
to abide by the ManDoc standard. Style changes include:
 * Upper-case letters before lower-case
 * List short options w/o arguments first
 * Then list short options w/ arguments
 * Then list long arguments

Reviewed-by: Brian Behlendorf <[email protected]>
Signed-off-by: Cameron Harr <[email protected]>
Closes #17357
behlendorf pushed a commit to behlendorf/zfs that referenced this pull request Jun 13, 2025
@cmharr @behlendorf
Reformat cli help and man page to be in sync
dd3e295 
The man page and CLI usage statements were both a little out
of sync and neither fully alphabetized correctly. That has
been fixed. One outstanding question is whether to get rid of
the ellipses on the CLI usage.

Reviewed-by: Brian Behlendorf <[email protected]>
Signed-off-by: Cameron Harr <[email protected]>
Closes openzfs#16004
Closes openzfs#17357
behlendorf pushed a commit to behlendorf/zfs that referenced this pull request Jun 13, 2025
@cmharr @behlendorf
Refactor man page and CLI help output per mandoc
71592e7 
The man page and the usage statement from the CLI have been refactored
to abide by the ManDoc standard. Style changes include:
 * Upper-case letters before lower-case
 * List short options w/o arguments first
 * Then list short options w/ arguments
 * Then list long arguments

Reviewed-by: Brian Behlendorf <[email protected]>
Signed-off-by: Cameron Harr <[email protected]>
Closes openzfs#17357
behlendorf pushed a commit that referenced this pull request Jun 17, 2025
@cmharr @behlendorf
Reformat cli help and man page to be in sync
289613c 
The man page and CLI usage statements were both a little out
of sync and neither fully alphabetized correctly. That has
been fixed. One outstanding question is whether to get rid of
the ellipses on the CLI usage.

Reviewed-by: Brian Behlendorf <[email protected]>
Signed-off-by: Cameron Harr <[email protected]>
Closes #16004
Closes #17357
behlendorf pushed a commit that referenced this pull request Jun 17, 2025
@cmharr @behlendorf
Refactor man page and CLI help output per mandoc
03a956e 
The man page and the usage statement from the CLI have been refactored
to abide by the ManDoc standard. Style changes include:
 * Upper-case letters before lower-case
 * List short options w/o arguments first
 * Then list short options w/ arguments
 * Then list long arguments

Reviewed-by: Brian Behlendorf <[email protected]>
Signed-off-by: Cameron Harr <[email protected]>
Closes #17357
behlendorf pushed a commit to behlendorf/zfs that referenced this pull request Jun 17, 2025
@cmharr @behlendorf
Reformat cli help and man page to be in sync
b647336 
The man page and CLI usage statements were both a little out
of sync and neither fully alphabetized correctly. That has
been fixed. One outstanding question is whether to get rid of
the ellipses on the CLI usage.

Reviewed-by: Brian Behlendorf <[email protected]>
Signed-off-by: Cameron Harr <[email protected]>
Closes openzfs#16004
Closes openzfs#17357
behlendorf pushed a commit to behlendorf/zfs that referenced this pull request Jun 17, 2025
@cmharr @behlendorf
Refactor man page and CLI help output per mandoc
cfb9cba 
The man page and the usage statement from the CLI have been refactored
to abide by the ManDoc standard. Style changes include:
 * Upper-case letters before lower-case
 * List short options w/o arguments first
 * Then list short options w/ arguments
 * Then list long arguments

Reviewed-by: Brian Behlendorf <[email protected]>
Signed-off-by: Cameron Harr <[email protected]>
Closes openzfs#17357
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@behlendorf behlendorf behlendorf approved these changes

Assignees
No one assigned
Labels
Status: Accepted Ready to integrate (reviewed, tested)
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@cmharr @behlendorf