[LU-5170] lfs usability Created: 10/Jun/14 Updated: 15/Dec/23
Status:	Open
Project:	Lustre
Component/s:	None
Affects Version/s:	Lustre 2.6.0
Fix Version/s:	None

Type:

Bug

Priority:

Minor

Reporter:

John Hammond

Assignee:

WC Triage

Resolution:

Unresolved

Votes:

Labels:

lfs, llnl, medium, utils

Issue Links:

Related
is related to	LUDOC-134	Completely document all lctl and lfs ...	Open
is related to	LU-13403	‘lfs mirror extend’ should not requir...	Open
is related to	LU-13435	"lfs mirror delete --mirror-id" argum...	Open
is related to	LU-15565	lfs getstripe --yaml should use an ar...	Open
is related to	~~LU-4824~~	lfs find should continue after errors	Resolved
is related to	~~LU-2740~~	lustre utils should support '--version'	Resolved
is related to	~~LU-4665~~	utils: lfs setstripe to specify OSTs	Resolved
is related to	LU-4959	"lfs\|lctl {function} --help" should s...	Open
is related to	LU-4315	split lfs.1 and lctl.8 man pages into...	Reopened
is related to	LU-8417	setstripe -o does not work on directo...	Open
is related to	LU-14554	Improve usability of "lfs mirror" com...	Open
is related to	LU-13720	"lfs mirror delete" should resync fil...	Open
is related to	LU-15856	"lfs setdirstripe -D ... <dir>" shoul...	Open
is related to	~~LU-16284~~	'lfs getstripe' follows symlink by de...	Resolved
is related to	LU-11875	"lfs find" does not return directorie...	Open
is related to	LU-16560	'lfs find -printf %w' does not print ...	Open
is related to	~~LU-16392~~	Bash completion regressions, lctl and...	Resolved
is related to	~~LU-17245~~	lfs utils: misleading error messages ...	Resolved
is related to	LU-15837	"lfs find -printf" improvements	Open
is related to	LU-10552	add "lfs find --mindepth"	Open
is related to	LU-13793	move "lfs quota" admin commands to lctl	Open
is related to	LU-13831	lfs mirror command to open a specific...	Open
is related to	LU-15276	DNE3: "lfs find" able to check defaul...	Open
is related to	LU-15504	"lfs find" is missing "-ls" support	Open
is related to	LU-15743	"lfs find" is missing "-xattr" support	Open
is related to	LU-16446	'lfs mirror extend' should allow spec...	Open
is related to	LU-16622	allow "lfs find --ost" to accept an O...	Open
is related to	~~LU-7495~~	lfs find is missing "-links" support	Resolved
is related to	~~LU-8207~~	Add auto-stripe option to lfs_migrate	Resolved
is related to	~~LU-10258~~	lfs mirror command to read/write spec...	Resolved
is related to	~~LU-10378~~	"lfs find" is missing "-printf" support	Resolved
is related to	~~LU-10482~~	enhance "lfs find" to add mirror rela...	Resolved
is related to	~~LU-11188~~	Add to "lfs find" the ability to chec...	Resolved
is related to	~~LU-11776~~	add "lfs find" support for directory ...	Resolved
is related to	~~LU-17370~~	simplify 'lfs --help' text output	Resolved

Severity:

Rank (Obsolete):

14249

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.

Comments

Comment by Matt Ezell [ 10/Jun/14 ]

Please be aware of ~~LU-4824~~ (http://review.whamcloud.com/9794) as patches are developed for this.

Comment by Andreas Dilger [ 09/Dec/16 ]

Patch http://review.whamcloud.com/11014 "~~LU-2740~~ utils: Add support for --version option" added the "--version" argument.

Comment by Gerrit Updater [ 05/Jan/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/24723
Subject: LU-5170 lfs: Standardize error messages in lfs utility
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 7ecf2f9dc7d0a6edb90efb3905abc863da9e9283

Comment by Andreas Dilger [ 06/Jan/17 ]

John, I just noticed here that you seem to advocate against prefixing error messages with error: or warning:? I'd prefer to keep those, as it makes it more clear to the user what is a fatal error, what is a significant warning, and what are just progress or normal output messages. I'm not dead set on this, but wanted to understand your motivation, as I typically add these prefixes into my error messages.

Comment by John Hammond [ 09/Jan/17 ]

(I don't feel so strongly on this point.) Usually anything pointed to stderr should be an error. Perhaps warnings could be labeled as such. But we should really try not to have an warnings. If something is deprecated then 'lfs: warning ... is deprecated' is fine. But in general I think that the message itself should make the severity clear.

x:~# ls history.out BARF c4038ab2.diff 
ls: cannot access BARF: No such file or directory
c4038ab2.diff  history.out

Comment by Gerrit Updater [ 16/Jan/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/24902
Subject: LU-5170 utils: Add support for --list-commands option
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 906be553276e1dc4f924bf016a99616a4f2a9c15

Comment by Gerrit Updater [ 15/Feb/17 ]

Oleg Drokin (oleg.drokin@intel.com) merged in patch https://review.whamcloud.com/24902/
Subject: LU-5170 utils: Add support for --list-commands option
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: 723f40030aa289f0b44d9394cc2e15a4d1772600

Comment by Gerrit Updater [ 14/Jul/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/28049
Subject: LU-5170 lfs: Standardize error messages in lfs_setstripe()
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 40559b037933a9b5780fdf4661e58b9b6ab89f7a

Comment by Gerrit Updater [ 17/Jul/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/28062
Subject: LU-5170 lfs: Standardize error messages in lfs_find()
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 4b716da54971ab599009e833cc52d7262d22a676

Comment by Gerrit Updater [ 18/Jul/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/28086
Subject: LU-5170 lfs: Standardize error messages in lfs_setdirstripe()
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 4490400ab50415477a38b11ac7e362fd09bdfc05

Comment by Gerrit Updater [ 26/Jul/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/28226
Subject: LU-5170 lfs: Standardize error messages in lfs_ladvise()
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: d317969e985f6a812b840d44eb74e40303d1eb08

Comment by Gerrit Updater [ 26/Jul/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/28234
Subject: LU-5170 lfs: Standardize error messages in set_time()
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 05f1b87991a21687630d3f44aa9c69788b11f067

Comment by Gerrit Updater [ 26/Jul/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/28239
Subject: LU-5170 lfs: Standardize error messages in lfs_mv()
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 7b4781e5c83bc7970c48acef8c18cbb5a81e9f46

Comment by Gerrit Updater [ 27/Jul/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/28250
Subject: LU-5170 lfs: Standardize error messages in macros
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 099415f4bb581c994e0e7b74fae629d330156c75

Comment by Gerrit Updater [ 27/Jul/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/28253
Subject: LU-5170 lfs: Standardize error messages in lfs_quota()
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 887731949f9358760d5826cb749e637ab9ade12d

Comment by Gerrit Updater [ 27/Jul/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/28255
Subject: LU-5170 lfs: Standardize error messages in lfs_component_del()
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 81e97ba0f5559ff9ef2c0366ccfb66c2af7611a2

Comment by Gerrit Updater [ 31/Jul/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/28286
Subject: LU-5170 lfs: Standardize error messages in lfs_setquota()
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 6c94f66d5fb2663141e18e647df39c782fe9ed83

Comment by Gerrit Updater [ 01/Aug/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/28304
Subject: LU-5170 lfs: Standardize error messages in adjust_first_extent
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 7013dd35293f4bebffdd63343c9e18f4e19824de

Comment by Gerrit Updater [ 16/Aug/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/28569
Subject: LU-5170 lfs: Standardize error messages in command parser
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 683f88a692a19443e6f933f773274d3eb5293b29

Comment by Gerrit Updater [ 16/Aug/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/28571
Subject: LU-5170 utils: Add utility and command name to llapi messages
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 89692ef5772fcab9eef140da8f0dc4e97ac46eb5

Comment by Gerrit Updater [ 31/Aug/17 ]

Oleg Drokin (oleg.drokin@intel.com) merged in patch https://review.whamcloud.com/28086/
Subject: LU-5170 lfs: Standardize error messages in lfs_setdirstripe()
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: 5eef95fee06f712694daba942f8e90a7df96e5e1

Comment by Gerrit Updater [ 08/Sep/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/28911
Subject: LU-5170 lfs: Standardize llapi messages used by lfs_setstripe
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: c2921cd875c307c4fe7a8d1ef0cd34e240e8803e

Comment by Gerrit Updater [ 14/Sep/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/28997
Subject: LU-5170 lfs: Standardize llapi messages for lfs_find()
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 9b7bcf03f0f2227fea024ef2d92693010e675ceb

Comment by Gerrit Updater [ 16/Oct/17 ]

Oleg Drokin (oleg.drokin@intel.com) merged in patch https://review.whamcloud.com/28049/
Subject: LU-5170 lfs: Standardize error messages in lfs_setstripe()
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: d94de5c04ee231f1820ae11ead86f0efc3c1fd02

Comment by Gerrit Updater [ 22/Nov/17 ]

Oleg Drokin (oleg.drokin@intel.com) merged in patch https://review.whamcloud.com/28255/
Subject: LU-5170 lfs: Standardize error messages in lfs_component_del()
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: f0f8d0c121ee3258bf444d9a3d3b83ace594340f

Comment by Gerrit Updater [ 22/Nov/17 ]

Oleg Drokin (oleg.drokin@intel.com) merged in patch https://review.whamcloud.com/28304/
Subject: LU-5170 lfs: Standardize error messages in adjust_first_extent
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: db831c666c24d23058021ca7e4a4cbaa63997fd9

Comment by Gerrit Updater [ 01/Dec/17 ]

Oleg Drokin (oleg.drokin@intel.com) merged in patch https://review.whamcloud.com/28250/
Subject: LU-5170 lfs: Standardize error messages in macros
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: ebb01c9421a8007a34b69eb972aab45369446b23

Comment by Gerrit Updater [ 28/Dec/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/30663
Subject: LU-5170 utils: Continue on error when multiple files requested
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 202f988f480a0b5aad09b1b4303ce5dcd924361d

Comment by Gerrit Updater [ 29/Dec/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/30664
Subject: LU-5170 lfs: Standardize llapi messages from lfs_setdirstripe
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: b8432851b9da636f38d930c45c32e80e7ae71c92

Comment by Gerrit Updater [ 29/Dec/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/30665
Subject: LU-5170 lfs: Standardize error messages in lfs_changelog()
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 88bc561da72ad814a25102345a89bc881064e411

Comment by Gerrit Updater [ 29/Dec/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/30666
Subject: LU-5170 lfs: Standardize error messages in lfs_check()
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 5822180560b90ba6dadc3edcc181d8ccce4ee470

Comment by Gerrit Updater [ 29/Dec/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/30667
Subject: LU-5170 lfs: Standardize error messages in lfs_data_version()
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 33fce299189f7390a8994a9c97379aecb8cf34e1

Comment by Gerrit Updater [ 29/Dec/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/30668
Subject: LU-5170 lfs: Standardize error messages in lfs_fid2path()
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 801daa7fb8022f2b341236a9e91e78957d80537e

Comment by Gerrit Updater [ 29/Dec/17 ]

Steve Guminski (stephenx.guminski@intel.com) uploaded a new patch: https://review.whamcloud.com/30670
Subject: LU-5170 lfs: Standardize error messages in lfs_path2fid()
Project: fs/lustre-release
Branch: master
Current Patch Set: 1
Commit: 1775a9aec1900f4a1a3775c3a933b59470f48c2d

Comment by Gerrit Updater [ 09/Jan/18 ]

Oleg Drokin (oleg.drokin@intel.com) merged in patch https://review.whamcloud.com/28253/
Subject: LU-5170 lfs: Standardize error messages in lfs_quota()
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: eea612b68943ec3f5bb8db40d00be1bdc4320c58

Comment by Gerrit Updater [ 09/Jan/18 ]

Oleg Drokin (oleg.drokin@intel.com) merged in patch https://review.whamcloud.com/28286/
Subject: LU-5170 lfs: Standardize error messages in lfs_setquota()
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: 10cf4dabc82f54cb7cf9dfc915d477bd6a9e42a7

Comment by Gerrit Updater [ 09/Jan/18 ]

Oleg Drokin (oleg.drokin@intel.com) merged in patch https://review.whamcloud.com/28571/
Subject: LU-5170 utils: Add utility and command name to llapi messages
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: 7a16f18ae1ef5d21812c916470022280617c4e91

Comment by Gerrit Updater [ 09/Jan/18 ]

Oleg Drokin (oleg.drokin@intel.com) merged in patch https://review.whamcloud.com/30666/
Subject: LU-5170 lfs: Standardize error messages in lfs_check()
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: bdc2923743f5541c2a72b5730c76bd96c45c9b18

Comment by Gerrit Updater [ 19/Apr/18 ]

Oleg Drokin (oleg.drokin@intel.com) merged in patch https://review.whamcloud.com/30665/
Subject: LU-5170 lfs: Standardize error messages in lfs_changelog()
Project: fs/lustre-release
Branch: master
Current Patch Set:
Commit: b7ac21b9c241b4aa291fd194d1b819e4f5172a4e