lsblk: allow to specify tree column

[thirdparty/util-linux.git] / misc-utils / lsblk.8

diff --git a/misc-utils/lsblk.8 b/misc-utils/lsblk.8
index ee1d873d07d491a62981a91012c00307fe33939d..07cd7a16fbbb1fdabde72cc9c39174bf939e9483 100644 (file)
--- a/misc-utils/lsblk.8
+++ b/misc-utils/lsblk.8
@@ -13,7 +13,9 @@ command reads the
 .B sysfs
 filesystem and
 .B udev db
-to gather information.
+to gather information. If the udev db is not available or lsblk is compiled without udev support than it
+tries to read LABELs, UUIDs and filesystem types from the block device. In this case root permissions
+are necessary.
 .PP
 The command prints all block devices (except RAM disks) in a tree-like format
 by default.  Use
@@ -21,13 +23,15 @@ by default.  Use
 to get a list of all available columns.
 .PP
 The default output, as well as the default output from options like
-.BR \-\-fs
+.B \-\-fs
 and
 .BR \-\-topology ,
 is subject to change.  So whenever possible, you should avoid using default
 outputs in your scripts.  Always explicitly define expected columns by using
 .B \-\-output
 .I columns-list
+and
+.B \-\-list
 in environments where a stable output is required.
 .PP
 Note that
@@ -41,7 +45,7 @@ before lsblk to synchronize with udev.
 .SH OPTIONS
 .TP
 .BR \-a , " \-\-all"
-Also list empty devices.  (By default they are skipped.)
+Also list empty devices and RAM disk devices.
 .TP
 .BR \-b , " \-\-bytes"
 Print the SIZE column in bytes rather than in a human-readable format.
@@ -53,10 +57,19 @@ Print information about the discarding capabilities (TRIM, UNMAP) for each devic
 Do not print holder devices or slaves.  For example, \fBlsblk --nodeps /dev/sda\fR prints
 information about the sda device only.
 .TP
+.BR \-E , " \-\-dedup " \fIcolumn\fP
+Use \fIcolumn\fP as a de-duplication key to de-duplicate output tree. If the
+key is not available for the device, or the device is a partition and parental
+whole-disk device provides the same key than the device is always printed.
+
+The usual use case is to de-duplicate output on system multi-path devices, for
+example by \fB\-E WWN\fR.
+.TP
 .BR \-e , " \-\-exclude " \fIlist\fP
 Exclude the devices specified by the comma-separated \fIlist\fR of major device numbers.
-Note that RAM disks (major=1) are excluded by default.  The filter is applied to the
-top-level devices only.
+Note that RAM disks (major=1) are excluded by default if \fB\-\-all\fR is no specified.
+The filter is applied to the top-level devices only. This maybe be confusing for
+\fB\-\-list\fR output format where hierarchy of the devices is not obvious.
 .TP
 .BR \-f , " \-\-fs"
 Output info about filesystems.  This option is equivalent to
@@ -70,7 +83,8 @@ Display help text and exit.
 .TP
 .BR \-I , " \-\-include " \fIlist\fP
 Include devices specified by the comma-separated \fIlist\fR of major device numbers.
-The filter is applied to the top-level devices only.
+The filter is applied to the top-level devices only. This maybe be confusing for
+\fB\-\-list\fR output format where hierarchy of the devices is not obvious.
 .TP
 .BR \-i , " \-\-ascii"
 Use ASCII characters for tree formatting.
@@ -79,7 +93,13 @@ Use ASCII characters for tree formatting.
 Use JSON output format.
 .TP
 .BR \-l , " \-\-list"
-Produce output in the form of a list.
+Produce output in the form of a list. The output does not provide information
+about relationships between devices and since version 2.34 every device is
+printed only once.
+.TP
+.BR \-M , " \-\-merge"
+Group parents of sub-trees to provide more readable output for RAIDs and
+Multi-path devices. The tree-like output is required.
 .TP
 .BR \-m , " \-\-perms"
 Output info about device owner, group and mode.  This option is equivalent to
@@ -117,6 +137,10 @@ Output info about SCSI devices only.  All partitions, slaves and holder devices
 Print dependencies in inverse order. If the \fB\-\-list\fR output is requested then
 the lines are still ordered by dependencies.
 .TP
+.BR \-T , " \-\-tree" [ =\fIcolumn ]
+Force tree-like output format.  If \fIcolumn\fP is specified, then a tree is printed in the column.
+The default is NAME column.
+.TP
 .BR \-t , " \-\-topology"
 Output info about block-device topology.
 This option is equivalent to
@@ -126,7 +150,18 @@ This option is equivalent to
 Display version information and exit.
 .TP
 .BR \-x , " \-\-sort " \fIcolumn\fP
-Sort output lines by \fIcolumn\fP. This option enables \fB\-\-list\fR output.
+Sort output lines by \fIcolumn\fP. This option enables \fB\-\-list\fR output format by default.
+It is possible to use the option \fI\-\-tree\fP to force tree-like output and
+than the tree branches are sorted by the \fIcolumn\fP.
+.TP
+.BR \-z , " \-\-zoned"
+Print the zone model for each device.
+.TP
+.BR " \-\-sysroot " \fIdirectory\fP
+Gather data for a Linux instance other than the instance from which the lsblk
+command is issued.  The specified directory is the system root of the Linux
+instance to be inspected.  This option is designed for the testing purpose.
+
 .SH NOTES
 For partitions, some information (e.g. queue attributes) is inherited from the
 parent device.
@@ -146,7 +181,7 @@ success
 .IP 1
 failure
 .IP 32
-not found all specified devices
+none of specified devices found
 .IP 64
 some specified devices found, some not found
 
@@ -156,6 +191,8 @@ Milan Broz <mbroz@redhat.com>
 Karel Zak <kzak@redhat.com>
 .fi
 .SH ENVIRONMENT
+.IP LSBLK_DEBUG=all
+enables lsblk debug output.
 .IP LIBBLKID_DEBUG=all
 enables libblkid debug output.
 .IP LIBMOUNT_DEBUG=all