You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Version/Platform/Processor information (from ipfs version --all): 16f8570 / 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:
ipfs ls - listing links from an object
ipfs object ls - listing ... links from an object
ipfs file ls - listing directory contents for unixfs objects
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.
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.
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.
@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?
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).
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.
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?
Activity
whyrusleeping commentedon Aug 8, 2016
The commands don't print this out, but the API does provide the information, try:
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 lslists unixfs directory contents.ipfs object lsisnt a command, you probably meanipfs object links. This (and the otherobjectcommands) is a plumbing command used to operate on and inspect merkledag graphs.ipfs file lsis a mostly deprecated command. It hasnt been removed because some applications still use it and we haven't officially migrated its functionality over intoipfs ls. Its original purpose was to provide more accurate size information of unixfs files and directories.ipfs files lsis 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/filesTo 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=jsonflag to each invocation.dokterbob commentedon Aug 8, 2016
@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 commentedon Aug 8, 2016
In addition to my latter remark, it seems that the
ipfs lscommand 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 commentedon Aug 8, 2016
Yes! that would be great.
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 commentedon Aug 9, 2016
So the following descriptions would need updating:
ipfs ls- https://github.com/ipfs/go-ipfs/blob/master/core/commands/ls.go#L35ipfs object links- https://github.com/ipfs/go-ipfs/blob/master/core/commands/object/object.go#L102ipfs file ls- https://github.com/ipfs/go-ipfs/blob/master/core/commands/unixfs/ls.go#L38ipfs files ls- https://github.com/ipfs/go-ipfs/blob/master/core/commands/files/files.go#L287For the descriptions I would interpret your previous comment.
[-]Expose unixfs object types in listings[/-][+]Sort out/document listing commands[/+][-]Sort out/document listing commands[/-][+]Document listing commands[/+][-]Document listing commands[/-][+]Better document listing commands[/+][-]Better document listing commands[/-][+]Document listing commands better[/+]dokterbob commentedon Aug 13, 2016
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 lsto add overipfs files ls?Again, would'nt it make sense to make
ipfs lsa mere alias foripfs files lsgiven that, essentially, both list unixfs files?Improve command documentation for listing commands (Fixes ipfs#3057).