fix(files): files:scan error ouput when user_id is not found + return correct exit status on error

[joshtrichards]

Summary

Note: This looks like a lengthier change than it really is due to moving the location of execute() for readability.

• Fixesocc files:scan misinterprets wrong path as username #27031 (improves error output when user_id in path is invalid)
• Fixesocc output not quiet when it should be, exit code not proper #27029 (adds exit status 1 if any errors occur during a run) [lines 154-156]
• Refactor: moves execute() function location to immediately after configure() for readability / consistency
• Expands occ command description and adds help
• Clarifies/streamlines language of argument/option explanations + uses capital letters at the beginning (to match rest of Command output)

TODO

• Determine whether exit code addition means this can't be backported (or whether it's a non-event since it's technically correcting a bug and/or adjusting undocumented behavior)

Notes

There are two behavior changes here to be aware of (in order order of probably significance in terms of being classified as a "breaking change"):

Exit code

Previously even where there were errors the exit code (i.e. echo $?) was still 0. Now any errors mean the code will be 1.

Output is slightly different when user_id is not found (e.g. see #27031 for existing behavior):

Now it is:

www-data@83e3407f887c:~/html$ ./occ files:scan -p "/a"
User 1 out of 1 not found (a)
+---------+-------+-----+---------+---------+--------+--------------+
| Folders | Files | New | Updated | Removed | Errors | Elapsed time |
+---------+-------+-----+---------+---------+--------+--------------+
| 0 | 0 | 0 | 0 | 0 | 1 | 00:00:00 |
+---------+-------+-----+---------+---------+--------+--------------+

Output

Output of occ files with this PR:

Available commands for the "files" namespace:
[...] files:repair-tree Try and repair malformed filesystem tree structures
files:scan Scans the filesystem for new files and updates the file cache
files:scan-app-data rescan the AppData folder
[...]

Output of occ files:scan --help with this PR:

Description:
Scans the filesystem for new files and updates the file cache
Usage:
files:scan [options] [--] [<user_id>...]
Arguments:
user_id Rescan all files of the specified user(s)
Options:
--output[=OUTPUT] Output format (plain, json or json_pretty, default is plain) [default: "plain"]
-p, --path=PATH Limit rescan to the specified path, eg. --path="/alice/files/Music". Overrides the user_id and --all parameters.
--generate-metadata[=GENERATE-METADATA] Generate metadata for all scanned files; if specified only generate for named value. [default: ""]
--all Rescan all files of all known users
--unscanned Only scan files which are marked as not fully scanned
--shallow Do not scan folders recursively
--home-only Only scan the home storage, ignoring any mounted external storage or share
-h, --help Display help for the given command. When no command is given display help for the list command
-q, --quiet Do not output any message
-V, --version Display this application version
--ansi|--no-ansi Force (or disable --no-ansi) ANSI output
-n, --no-interaction Do not ask any interactive question
--no-warnings Skip global warnings, show command output only
-v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug
Help:
You can rescan all files or only those of select user(s) or a select path. Statistics will be shown at the end of the scan by default.

Checklist

• Code is properly formatted
• Sign-off message is added to all commits
• Tests (unit, integration, api and/or acceptance) are included
• Screenshots before/after for front-end changes
• Documentation (manuals or wiki) has been updated or is not required
• Backports requested where applicable (ex: critical bugfixes)

[joshtrichards]

Suggested change

	'Limit rescan to the specified path, eg. --path="/alice/files/Music". Overrides the user_id and --all parameters; the user_id is determined from the path.'
	'Limit rescan to the specified path, eg. --path="/alice/files/Music". Overrides the user_id and --all parameters.'

[artonge]

Maybe do not move the execute method to ease the review, or do that in a different commit :)

[artonge]

Maybe more explicit, as it does not only detect new files.

Suggested change

	->setDescription('Scans the filesystem for new files and updates the file cache')
	->setDescription('Scans the filesystem and updates the file cache acording to the detected additions, deletions and updates.')

[salmart-dev]

Hey @joshtrichards this PR is quite old, do you want to keep it still open? If so, could you please rebase it and split the changes in different commits, so it's easier to review the changes?