Description
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.
Attachments
Issue Links
- is related to
-
LU-11875 "lfs find" does not return directories when searching for default layouts
-
- Open
-
-
-
- Open
-
-
-
- Resolved
-
-
-
- Resolved
-
-
LU-15837 "lfs find -printf" improvements
-
- Open
-
-
-
- Open
-
-
-
- Open
-
-
-
- Open
-
-
-
- Open
-
-
-
- Open
-
-
-
- Open
-
-
-
- Open
-
-
-
- Open
-
-
-
- Resolved
-
-
-
- Resolved
-
-
-
- Resolved
-
-
-
- Resolved
-
-
-
- Resolved
-
-
-
- Resolved
-
-
-
- Resolved
-
-
-
- Resolved
-
-
-
- Resolved
-
- is related to
-
-
- Open
-
-
-
- Open
-
-
-
- Open
-
-
-
- Open
-
-
-
- Resolved
-
-
-
- Resolved
-
-
LU-4665 utils: lfs setstripe to specify OSTs
-
- Resolved
-
-
LU-4959
"lfs|lctl {function} --help" should show "lfs-{function}" man page
-
- Open
-
-
LU-4315
split lfs.1 and lctl.8 man pages into one page per subcommand
-
- Reopened
-
-
-
- Open
-
-
-
- Open
-
-
-
- Open
-
-
-
- Open
-
-
-
- Resolved
-