Skip to content
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

zfs.8 man page snapshot listing instructions are confusing #11562

Closed
ThePythonicCow opened this issue Feb 3, 2021 · 0 comments
Closed

zfs.8 man page snapshot listing instructions are confusing #11562

ThePythonicCow opened this issue Feb 3, 2021 · 0 comments
Labels
Type: Documentation Indicates a requested change to the documentation

Comments

@ThePythonicCow
Copy link

### System information

Distribution Name | Ubuntu
Distribution Version | 20.04.2 LTS
Linux Kernel | 5.4.0-65
Architecture | amd64 (Ryzen)
ZFS Version | 0.8.3-1ubuntu12.5
SPL Version | 0.8.3-1ubuntu12.5

### Describe the problem you're observing

Incomplete description in zfs.8 man page for listing snapshots confused me.

### Describe how to reproduce the problem

Step 1: Forget what you know about zfs and pretend to be a newbie.
Step 2: Create a couple of snapshots
Step 3: Try to list your new snapshots using the instructions in the zfs.8 man page.

### Include any warning/errors/backtraces from the system logs

The zfs.8 man page describes in 3 places how to include snapshots in "zfs list":

These 3 places state:

  1. Snapshots are displayed if the listsnaps property is on (the default is off).
  2. Snapshots are displayed if the listsnaps property is on. The default is off. See zpool(8) for more information on pool properties.
  3. For example, specifying -t snapshot displays only snapshots.

The first of these has twice now (I'm just learning zfs) sent me down a rabbit hole, looking for a zfs dataset property "listsnaps". There is no such property (of datasets).

I'm on version 0.8.3 of zfsutils-linux that has this man page, but when I look at https://zfsonlinux.org/manpages/0.8.6/man8/zfs.8.html it seems that the above is still true in 0.8.6

Suggestion, to help us newbies reduce our learning time to list snapshots:

Change the first sentence or two of both of the first 2 of the above 3 places in zfs.8 to:

"zfs list" displays snapshots only if either the "listsnapshots" property of the underlying zpool is on (the default is off), or if the "zfs list -t snapshot" option is specified.
@ThePythonicCow ThePythonicCow added Status: Triage Needed New issue which needs to be triaged Type: Defect Incorrect behavior (e.g. crash, hang) labels Feb 3, 2021
@behlendorf behlendorf added Type: Documentation Indicates a requested change to the documentation and removed Status: Triage Needed New issue which needs to be triaged Type: Defect Incorrect behavior (e.g. crash, hang) labels Feb 3, 2021
behlendorf added a commit to behlendorf/zfs that referenced this issue Feb 3, 2021
@behlendorf
zfs-list.8: clarify listing snapshots
9d4014e 
Clarify how to include snapshots in the `zpool list` outpool by
referencing the full name of the listsnapshots pool property, and
the `zpool list -t snapshot` option.

Signed-off-by: Brian Behlendorf <behlendorf1@llnl.gov>
Issue openzfs#11562
@behlendorf behlendorf mentioned this issue Feb 3, 2021
Merged
13 tasks
behlendorf added a commit to behlendorf/zfs that referenced this issue Feb 3, 2021
@behlendorf
zfs-list.8: clarify listing snapshots
449231c 
Clarify how to include snapshots in the `zpool list` outpool by
referencing the full name of the listsnapshots pool property, and
the `zpool list -t snapshot` option.

Signed-off-by: Brian Behlendorf <behlendorf1@llnl.gov>
Issue openzfs#11562
behlendorf added a commit to behlendorf/zfs that referenced this issue Feb 3, 2021
@behlendorf
zfs-list.8: clarify listing snapshots
5fcea66 
Clarify how to include snapshots in the `zpool list` outpool by
referencing the full name of the `listsnapshots` pool property,
and the `zpool list -t snapshot` option.

Signed-off-by: Brian Behlendorf <behlendorf1@llnl.gov>
Issue openzfs#11562
behlendorf added a commit that referenced this issue Feb 5, 2021
@behlendorf
zfs-list.8: clarify listing snapshots
fb0d807 
Clarify how to include snapshots in the `zpool list` output by
referencing the full name of the `listsnapshots` pool property,
and the `zpool list -t snapshot` option.

Reviewed-by: Matthew Ahrens <mahrens@delphix.com>
Reviewed-by: George Melikov <mail@gmelikov.ru>
Signed-off-by: Brian Behlendorf <behlendorf1@llnl.gov>
Closes #11562
Closes #11565
jsai20 pushed a commit to jsai20/zfs that referenced this issue Mar 30, 2021
@behlendorf @jsai20
zfs-list.8: clarify listing snapshots
4d82ece 
Clarify how to include snapshots in the `zpool list` output by
referencing the full name of the `listsnapshots` pool property,
and the `zpool list -t snapshot` option.

Reviewed-by: Matthew Ahrens <mahrens@delphix.com>
Reviewed-by: George Melikov <mail@gmelikov.ru>
Signed-off-by: Brian Behlendorf <behlendorf1@llnl.gov>
Closes openzfs#11562
Closes openzfs#11565
sempervictus pushed a commit to sempervictus/zfs that referenced this issue May 31, 2021
@behlendorf
zfs-list.8: clarify listing snapshots
86ebf3f 
Clarify how to include snapshots in the `zpool list` output by
referencing the full name of the `listsnapshots` pool property,
and the `zpool list -t snapshot` option.

Reviewed-by: Matthew Ahrens <mahrens@delphix.com>
Reviewed-by: George Melikov <mail@gmelikov.ru>
Signed-off-by: Brian Behlendorf <behlendorf1@llnl.gov>
Closes openzfs#11562
Closes openzfs#11565
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Type: Documentation Indicates a requested change to the documentation
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@behlendorf @ThePythonicCow