[LU-17370] simplify 'lfs --help' text output

Blocker — Sun, 4 Feb 2024 14:49:29 +0000

Currently, the usage and --help text output for "lfs COMMAND" is inconsistent and can produce a lot of output. This often includes detailed descriptions of the options, their parameters, and different usage modes. For example, if a bad parameter is given to "lfs setstripe" it will generate 104 lines of output:

$ lfs setstripe --bad foo
lfs setstripe setstripe: unrecognized option '--bad'
To create a file with specified striping/composite layout, or
create/replace the default layout on an existing directory:
usage: setstripe [--component-end|-E <comp_end>]
                 [--stripe-count|-c <stripe_count>]
                 [--overstripe-count|-C <stripe_count>]
                 [--stripe-index|-i <start_ost_idx>]
                 [--stripe-size|-S <stripe_size>]
                 [--compress|-Z <compr_type>[:<compr_level>]
                 [--compress-type=<compress_type>
                 [--compress-level=<compress_level>
                 [--compress-chunk=<chunk_size>]
                 [--extension-size|--ext-size|-z]
                 [--layout|-L <pattern>]
                 [--mirror-count|-N[mirror_count]]
                 [--ost|-o <ost_indices>]
                 [--pool|-p <pool_name>]
                 [--yaml|-y <yaml_template_file>]
                 [--copy=<lustre_src>]
                 [--mode <mode>]
                 <directory|filename>
 or
To add component(s) to an existing composite file:
usage: setstripe --component-add [--component-end|-E <comp_end>]
                 [--stripe-count|-c <stripe_count>]
                 [--overstripe-count|-C <stripe_count>]
                 [--stripe-index|-i <start_ost_idx>]
                 [--stripe-size|-S <stripe_size>]
                 [--compress|-Z <compr_type>[:<compr_level>]
                 [--compress-type=<compress_type>
                 [--compress-level=<compress_level>
                 [--compress-chunk=<chunk_size>]
                 [--extension-size|--ext-size|-z]
                 [--layout|-L <pattern>]
                 [--mirror-count|-N[mirror_count]]
                 [--ost|-o <ost_indices>]
                 [--pool|-p <pool_name>]
                 [--yaml|-y <yaml_template_file>]
                 [--copy=<lustre_src>]
	stripe_count: Number of OSTs to stripe on (0=fs default, -1 all)
	              Using -C instead of -c allows overstriping, which
	              will place more than one stripe per OST if
	              stripe_count is greater than the number of OSTs.
	start_ost_idx: OST index of first stripe (-1=default round robin)
	stripe_size:  Number of bytes on each OST (0=fs default)
	              Optional K, M, or G suffix (for KB, MB, GB
	              respectively).  Must be a multiple of 64KiB.
	compress:
	              Compression algorithm <type> and compress <level>.
	              The compress level showed in getstripe could be 
	              not exactly the one input here.
	compress-chunk:
	              Compression data chunk size in KiB, the value
	              will be adjusted to power-of-two multiples of the
	              base 64KiB.
	extension_size:
	              Number of bytes the previous component is extended
	              each time. Optional K, M, or G suffix (for KB,
	              MB, GB respectively)
	pool_name:    Name of OST pool to use (default none)
	layout:       stripe pattern type: raid0, mdt (default raid0)
	ost_indices:  List of OST indices, can be repeated multiple times
	              Indices be specified in a format of:
	                -o <ost_1>,<ost_i>-<ost_j>,<ost_n>
	              Or:
	                -o <ost_1> -o <ost_i>-<ost_j> -o <ost_n>
	              If --pool is set with --ost then the OSTs
	              must be the members of the pool.
	comp_end:     Extent end of component, start after previous end.
	              Optional K, M, or G suffix (for KiB, MiB, GiB), or
	              -1 or 'eof' for max file size). Must be a multiple
	              of stripe_size and a multiple of 64KiB.
	yaml_template_file:
	              YAML layout template file, can't be used with -c,
	              -i, -S, -p, -o, or -E arguments.
	lustre_src:   Lustre file/dir whose layout info is used to set
	              another lustre file or directory, can't used with
	              -c, -i, -S, -p, -o, or -E arguments.
To totally delete the default striping from an existing directory:
usage: setstripe [--delete|-d] <directory>
 or
To create a mirrored file or set s default mirror layout on a directory:
usage: setstripe {--mirror-count|-N}[mirror_count] [SETSTRIPE_OPTIONS] <directory|filename>
 or
To delete the last component(s) from an existing composite file
(note that this will also delete any data in those components):
usage: setstripe --component-del [--component-id|-I <comp_id>]
                               [--component-flags|-F <comp_flags>]
                               <filename>
	comp_id:     Unique component ID to delete
	comp_flags:  'init' indicating all instantiated components
	             '^init' indicating all uninstantiated components
	-I and -F cannot be specified at the same time
 or
To set or clear flags on a specific component
(note that this command can only be applied to mirrored files:
usage: setstripe --comp-set {-I comp_id|--comp-flags=comp_flags}
                            <filename>
 or
To create a file with a foreign (free format) layout:
usage: setstripe --foreign[=<foreign_type>]
                 --xattr|-x <layout_string> [--flags <hex>]
                 [--mode <mode>] <filename>

Unfortunately, this large number of lines will scroll the important error message off the top of the terminal screen and show only relatively useless information about obscure usage options at the end.

The "lfs" commands usage/help text should be changed to print a single line description of the command and a list of all command-line options. This will keep the important usage error message visible on the screen, and makes the rest of the text much more readable.

Also, the bash_completion functionality (~~LU-13225~~) runs the command with "help" to generate a list of short/long options for tab completion (e.g. "lfs setstripe --<TAB><TAB>") so having the command-line options shown properly for all commands (in particular "lfs mirror" and "lfs migrate") instead of by reference (e.g. "SETSTRIPE_OPTIONS") simplifies the implementation of these tools.

Whamcloud Community JIRA

[LU-17370] simplify 'lfs --help' text output