[LU-5170] lfs usability

Related — Fri, 15 Dec 2023 20:01:53 +0000

lfs usability needs attention.

Command output

Structured command output should be clear, unambiguous, minimalist, and easily parsed (by awk).

Errors and Error Messages

Except for unrecognized/bad command/option usage, error messages must be one line only and prefixed by 'lfs COMMAND: '. Text that follows 'lfs COMMAND: ' should start with a lowercase word like cannot. A period should not be used at the end of an error message.
There must be a strong reason not to use an error message of the form
```
lfs COMMAND: cannot VERB 'ARG': STRERROR
```

Commands that take multiple (file) arguments should continue on error but report the error. Note that using touch the second file is not created but the third is. This is unix convention and should be followed by lfs. A patch has been submitted at https://review.whamcloud.com/#/c/30663/.

# cd /mnt/lustre
# ls
# touch f0 d1/f1 f2
touch: cannot touch `d1/f1': No such file or directory
# echo $?
1
# ls
f0  f2
#
# rm f0 f2
# lfs setstripe -c4 f0 d1/f1 f2
unable to open 'd1/f1': No such file or directory (2)
error: setstripe: create stripe file 'd1/f1' failed
# echo $?
2
# ls
f0

Commands and Options

Passing unrecognized commands and options should generate a two line error message. We shouldn't "spam the console" since these are usually just simple typos and printing a long error message may scroll away something the user cared about.

# lfs setstrip
Try interactive use without arguments or use one of:
"setstripe"
"getstripe"
"setdirstripe"
"getdirstripe"
"mkdir"
"rm_entry"
"pool_list"
"find"
"check"
"join"
"osts"
"mdts"
"df"
"getname"
"quotacheck"
"quotaon"
"quotaoff"
"setquota"
"quota"
"flushctx"
"lsetfacl"
"lgetfacl"
"rsetfacl"
"rgetfacl"
"cp"
"ls"
"changelog"
"changelog_clear"
"fid2path"
"path2fid"
"data_version"
"hsm_state"
"hsm_set"
"hsm_clear"
"hsm_action"
"hsm_archive"
"hsm_restore"
"hsm_release"
"hsm_remove"
"hsm_cancel"
"swap_layouts"
"migrate"
"mv"
"help"
"exit"
"quit"
as argument.

Should be:

# lfs setstrip
lfs: unrecognized command 'setstrip'
Try 'lfs --help' for more information

A patch has been submitted at https://review.whamcloud.com/#/c/28569/.

'lfs --help' should generate a short help message, not a list of subcommands.

# lfs --help
Try interactive use without arguments or use one of:
"setstripe"
"getstripe"
"setdirstripe"
"getdirstripe"
"mkdir"
"rm_entry"
"pool_list"
...

Should be:

usage: lfs COMMAND [OPTIONS]... ARGS
...

Note also that 'lfs setstrip -c11 xyzzy' prints nothing to stderr.

'lfs help COMMAND' should print help to stdout and not to stderr.
Wrong:

# lfs help setstripe > /dev/null
setstripe: Create a new file with a specific striping pattern or
set the default striping pattern on an existing directory or
delete the default striping pattern from an existing directory
usage: setstripe -d <directory>   (to delete default striping)
 or
usage: setstripe [--stripe-count|-c <stripe_count>]
                 [--stripe-index|-i <start_ost_idx>]
                 [--stripe-size|-S <stripe_size>]
                 [--pool|-p <pool_name>]
                 [--block|-b] <directory|filename>
...

A patch has been submitted at https://review.whamcloud.com/#/c/28569/.

'lfs help COMMAND' should be equivalent to 'lfs COMMAND --help'
Wrong:

# lfs setdirstripe --help
setdirstripe: unrecognized option '--help'
error: setdirstripe: option '--help' unrecognized
To create a remote directory on a specified MDT.
usage: setdirstripe <--count|-c stripe_count>
[--index|-i mdt_index] [--hash-type|-t hash_type]
[--default_stripe|-D ] <dir>
	stripe_count: stripe count of the striped directory
	mdt_index:	MDT index of first stripe
	hash_type:	hash type of the striped directory. Hash types:
	-t fnv_1a_64 FNV-1a hash algorithm(default)
	-t all_char  sum of characters % MDT_COUNT. (not recommended)
	default_stripe: set default dirstripe of the directory

Options must use dashes (instead of underscores) to separate words.
```
Wrong: --stripecount
Wrong: --stripe_count
Right: --stripe-count
```
Existing options that use underscores should be accepted in future versions of lfs. But s/_/-/ equivalents should be added and help messages and manpages should be updated to use these forms.

Paths (and other string argumenst) used in error messages must be enclosed in single quotes.

Help messages should look more unixy.

# lfs help setstripe
setstripe: Create a new file with a specific striping pattern or
set the default striping pattern on an existing directory or
delete the default striping pattern from an existing directory
usage: setstripe -d <directory>   (to delete default striping)
 or
usage: setstripe [--stripe-count|-c <stripe_count>]
                 [--stripe-index|-i <start_ost_idx>]
                 [--stripe-size|-S <stripe_size>]
                 [--pool|-p <pool_name>]
                 [--block|-b] <directory|filename>
	stripe_size:  Number of bytes on each OST (0 filesystem default)
	              Can be specified with k, m or g (in KB, MB and GB
	              respectively)
	start_ost_idx: OST index of first stripe (-1 default)
	stripe_count: Number of OSTs to stripe over (0 default, -1 all)
	pool_name:    Name of OST pool to use (default none)
	block:	 Block file access during data migration

Error messages should be groomed.

Wrong:
unable to open 'd1/f1': No such file or directory (2)
error: setstripe: create stripe file 'd1/f1' failed
Right:
lfs setstripe: cannot open 'd1/f1': No such file or directory

Help messages (and manpages) should be checked for correctness and completeness.
Help messages should use conventional unix style. DIR, FILE, --mode=MODE instead of <dir>, <file>, --mode=<mode>.
Commands that accept multiple files should advertise this by using FILE... in help messages.
'lfs --usage' and 'lfs --version' should be supported.
'lfs --list-commands' should be supported.
A patch has already landed.

These and other standards for usability should be expanded, refined, made available to the development community, and used to validate additions/changes to lfs and other command line utilities.

Whamcloud Community JIRA

[LU-5170] lfs usability

Command output

Errors and Error Messages

Commands and Options