files_external:list --importable-format documentation

[phil-davis]

Fixes issue #2674
core code changes were merged in PR owncloud/core#37513 for 10.5.0

Backport to 10.5 only.

[mmattel]

From core:

A new option to files_external:list has been added - -i or --importable-format - when this
is specified and a JSON output is requested, the items above are corrected in the JSON
to be in a format that can be used for import.

This reads for me that -i needs a proper output format (json or json_pretty ?) to be defined - but not plain which is used by default.

[phil-davis]

@mmattel any output format is valid. If used with a "normal" list then the text columns for Storage and Authentication Type show the "technical" values rather than the "human readable" values.

See owncloud/core#37513 (comment) - @jvillafanez also asked about this. It's good to see that reviewers are looking :)

[mmattel]

I have tested it just now.
I propose to add a text below the table like:

...
TIP: When using option --importable-format, consider using --show-password additionally. Else the user and/or admin has to change all mount passwords post importing manually to make mounts fully functional.
...

This is because if you miss --show-password, an import needs post work for either the user and/or the admin !

[phil-davis]

This is because if you miss --show-password, an import needs post work for either the user and/or the admin !

OK, I will look at it. The "problem" here is that the new --importable-format option has only been added so that files_external:export can switch it on. The availability to someone manually doing files_external:list --importable-format is really an accidental side-effect. There is no intention for files_external:list --importable-format by itself to produce the output ready for files_external:import - for that there is the command files_external:export which puts together all the pieces that are needed.

[mmattel]

I think that the current implementation has a positive sideffect.
You have to mandatory add another option to make it fully work for importing.
This is a security measure ! 😄
The only thing is, it must be documented.
Just thinking about, instead of a tip, we can write NOTE: and start with: For security measures you have to add...

[phil-davis]

@mmattel I wrote a "Note:" section

[phil-davis]

Backport to 10.5 is PR #2678