Go-ipfs: Document listing commands better

[dokterbob]

Version/Platform/Processor information (from ipfs version --all): 16f857040fadf07d947c1b6fbcf90aec8994d1d2 / 0.4.2
Type (bug, feature, meta, test failure, question): feature
Area (api, commands, daemon, fuse, etc): api
Priority (from P0: functioning, to P4: operations on fire): P3

Description:
Currently, the ipfs command (and API) expose three different kinds of listing commands:

• [x] ipfs ls - listing links from an object
• [x] ipfs object ls - listing ... links from an object
• [x] ipfs file ls - listing directory contents for unixfs objects
• [x] ipfs files ls - listing directory contents for ...unixfs objects

Apart from the fact that listing commands obviously needed to be sorted out (for which I created #3056), none of these commands actually exposes the data type of objects (whether they are a file, directory, metadata a symlink or plain data) while this data is in fact stored in the unixfs protobuf. Simply exposing this data (through the API and commands) would creating file-based applications a lot easier.

WIP for this one in https://github.com/dokterbob/go-ipfs/tree/lshelpdoc

[whyrusleeping]

The commands don't print this out, but the API does provide the information, try:

$ ipfs ls --enc=json <hash>

If you want to have this information exposed as normal text output, we could add a flag (maybe -l). As always, pull requests accepted :)

To address your other point:

• ipfs ls lists unixfs directory contents.
• ipfs object ls isnt a command, you probably mean ipfs object links. This (and the other object commands) is a plumbing command used to operate on and inspect merkledag graphs.
• ipfs file ls is a mostly deprecated command. It hasnt been removed because some applications still use it and we haven't officially migrated its functionality over into ipfs ls. Its original purpose was to provide more accurate size information of unixfs files and directories.
• ipfs files ls is a command for viewing files in the local mutable namespace. Take a look at the guide to this that I wrote recently: https://github.com/ipfs/examples/tree/master/examples/files

To better understand the purpose of each command I encourage you to take a look at the actual raw output that each command provides by adding the --enc=json flag to each invocation.

[dokterbob]

@whyrusleeping Thanks for the quick reply. I guess you're right in tagging it as a documentation issue. Would you appreciate concerete suggestions with regards to the descriptions of the commands?

[dokterbob]

In addition to my latter remark, it seems that the ipfs ls command also lists parts of files - with the same data type of a file. Is this intended behaviour?

Might it not preferable to have parts-of-files be labeled either as Raw or as some other type? The rationale for this being that parts of files should be treated differently (i.e. with regards to content type detection).

[whyrusleeping]

Would you appreciate concerete suggestions with regards to the descriptions of the commands?

Yes! that would be great.

it seems that the ipfs ls command also lists parts of files

This is as intended. A larger file will be 'sharded', indirect blocks have no real difference from the actual root node of the file, they get processed exactly the same way, and you can even refer to a sub-section of a file by the hash of one of the indirect blocks. The leaf nodes that don't have any children are marked as Raw.

[dokterbob]

So the following descriptions would need updating:

• ipfs ls - https://github.com/ipfs/go-ipfs/blob/master/core/commands/ls.go#L35
• ipfs object links - https://github.com/ipfs/go-ipfs/blob/master/core/commands/object/object.go#L102
• ipfs file ls - https://github.com/ipfs/go-ipfs/blob/master/core/commands/unixfs/ls.go#L38
• ipfs files ls - https://github.com/ipfs/go-ipfs/blob/master/core/commands/files/files.go#L287

For the descriptions I would interpret your previous comment.

[dokterbob]

Looking into this a little further, specifically considering #2837 (allowing files command to handle ipfs paths), what added or specific functionality is meant for ipfs ls to add over ipfs files ls?

Again, would'nt it make sense to make ipfs ls a mere alias for ipfs files ls given that, essentially, both list unixfs files?