zfs.8 man page snapshot listing instructions are confusing

[Paul Jackson]

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

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 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, or if the "zfs list -t snapshot" option is specified.

Extra Credit:

Just now it seems to me that the following command does _NOT_ list snapshots, on a dataset that has some snapshots ... so the zfs.8 documentation that the "zfs list -t type" can be a "comma-separated list of types to display" seems incorrect:

zfs list -t filesystem,snapshot myzfsdataset

Whether this "Extra Credit" discrepancy is a bug in the documentation, or in the zfs command code, or newbie operator error, I'll leave as an exercise to the reader <grin>.

ProblemType: Bug
DistroRelease: Ubuntu 20.04
Package: zfsutils-linux 0.8.3-1ubuntu12.5
ProcVersionSignature: Ubuntu 5.4.0-64.72-generic 5.4.78
Uname: Linux 5.4.0-64-generic x86_64
NonfreeKernelModules: zfs zunicode zavl icp zcommon znvpair nvidia_modeset nvidia
ApportVersion: 2.20.11-0ubuntu27.14
Architecture: amd64
CasperMD5CheckResult: skip
CurrentDesktop: XFCE
Date: Tue Jan 26 13:41:16 2021
SourcePackage: zfs-linux
UpgradeStatus: No upgrade log present (probably fresh install)
modified.conffile..etc.sudoers.d.zfs: [inaccessible: [Errno 13] Permission denied: '/etc/sudoers.d/zfs']

[Richard Laager (rlaager)]

listsnaps is an alias of listsnapshots, but you're right that it's on the pool.

Can you file this upstream:
https://github.com/openzfs/zfs/issues/new/choose

If you want, you could take a stab at submitting a pull request. It's a pretty simple sounding change. The repo is here: https://github.com/openzfs/zfs The man pages are in the "man" subdirectory.

For your "Extra Credit" piece, "zfs list -t filesystem,snapshot" shows both filesystems and snapshots for everything. "zfs list -t snapshot dataset" shows snapshots for the specified dataset. But if you combine those together as "zfs list -t filesystem,snapshot dataset", you do not get snapshots. However, "zfs list -t filesystem,snapshot -r dataset" does show the snapshots. Whether that's a bug or not, I can't say. But that's a more detailed explanation of that problem that will be helpful if you file a bug report on that.

[Paul Jackson (thepythoniccow)]

Filed upstream, as you suggested:

https://github.com/openzfs/zfs/issues/11562

It's been a couple of years since I've pushed a pull request on github, so I'll probably remain lazy and not get around to it in this case, to avoid the extra time it would take me to recall just how to do it. A few minutes work for someone actively familiar with the process is likely a couple hours work for a (relapsed back to) clueless git such as myself.

Thanks for your spot on initial response to this here bug. Keep up the good zfs work.

[Colin Ian King (colin-king)]

Fix landed upstream:

commit d66f017c1775952a1923031039fdfb1ac28a34f4
Author: Brian Behlendorf <email address hidden>
Date: Thu Feb 4 09:56:28 2021 -0800

    zfs-list.8: clarify listing snapshots

[Colin Ian King (colin-king)]

Fix released in 2.0.3-8ubuntu3 (21.10 Impish), zfs-linux_2.0.2-1ubuntu5 (21.04 Hirsute)