From 8604e67dc9b96688f5b545cbc3a271cb0b03ad7e Mon Sep 17 00:00:00 2001 From: Shawn Bayern Date: Mon, 25 Aug 2025 19:45:47 -0400 Subject: [PATCH] Add description of default sorting behavior to zfs_list.8 The sorting logic is all in cmd/zfs/zfs_iter.c. I borrowed where I could from the comments in the source code, but please note that the comment to zfs_sort() is a little imprecise, or at least incomplete, because it doesn't give any indication of the chronological sort that will be used by default for snapshots in zfs_compare(). While adding this description, I took the liberty to copy-edit the rest of the file lightly. In those edits, I've removed "If specified, you can list property information by the absolute pathname or the relative pathname" because, in context, it seems more confusing than helpful. Reviewed-by: Brian Behlendorf Reviewed-by: George Melikov Reviewed-by: Tony Hutter Reviewed-by: Rob Norris Signed-off-by: Shawn Bayern Closes #15713 Closes #15869 --- man/man8/zfs-list.8 | 45 +++++++++++++++++++++++++++------------------ 1 file changed, 27 insertions(+), 18 deletions(-) diff --git a/man/man8/zfs-list.8 b/man/man8/zfs-list.8 index 677d8292e..eed1307cc 100644 --- a/man/man8/zfs-list.8 +++ b/man/man8/zfs-list.8 @@ -50,27 +50,25 @@ .Oo Ar filesystem Ns | Ns Ar volume Ns | Ns Ar snapshot Oc Ns … . .Sh DESCRIPTION -If specified, you can list property information by the absolute pathname or the -relative pathname. -By default, all file systems and volumes are displayed. +By default, all file systems and volumes are displayed, with the following +fields: +.Sy name , Sy used , Sy available , Sy referenced , Sy mountpoint . Snapshots are displayed if the .Sy listsnapshots pool property is .Sy on .Po the default is .Sy off -.Pc , +.Pc or if the .Fl t Sy snapshot or .Fl t Sy all options are specified. -The following fields are displayed: -.Sy name , Sy used , Sy available , Sy referenced , Sy mountpoint . .Bl -tag -width "-H" .It Fl H Used for scripting mode. -Do not print headers and separate fields by a single tab instead of arbitrary +Do not print headers, and separate fields by a single tab instead of arbitrary white space. .It Fl j , -json Op Ar --json-int Print the output in JSON format. @@ -87,7 +85,7 @@ of will display only the dataset and its direct children. .It Fl o Ar property A comma-separated list of properties to display. -The property must be: +Each property must be: .Bl -bullet -compact .It One of the properties described in the @@ -125,30 +123,41 @@ section of or the value .Sy name to sort by the dataset name. -Multiple properties can be specified at one time using multiple +Multiple properties can be specified to operate together using multiple .Fl s -property options. +or +.Fl S +options. Multiple .Fl s -options are evaluated from left to right in decreasing order of importance. -The following is a list of sorting criteria: +and +.Fl S +options are evaluated from left to right to supply sort keys in +decreasing order of priority. +Property types operate as follows: .Bl -bullet -compact .It Numeric types sort in numeric order. .It String types sort in alphabetical order. .It -Types inappropriate for a row sort that row to the literal bottom, regardless of -the specified ordering. +Types inappropriate for a row sort that row to the literal bottom, +regardless of the specified ordering. .El .Pp -If no sorting options are specified the existing behavior of -.Nm zfs Cm list -is preserved. +If no sort columns are specified, or if two lines of output would sort +equally across all specified columns, then datasets and bookmarks are +sorted by name, whereas snapshots are sorted first by the name of their +dataset and then by the time of their creation. +When no sort columns are specified but snapshots are listed, this +default behavior causes snapshots to be grouped under their datasets in +chronological order by creation time. .It Fl S Ar property Same as .Fl s , -but sorts by property in descending order. +but sorts by +.Ar property +in descending order. .It Fl t Ar type A comma-separated list of types to display, where .Ar type