Skip to content

Document listing commands betterΒ #3057

Closed

Description

@dokterbob

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.

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

Activity

  1. whyrusleeping commented on Aug 8, 2016

    @whyrusleeping
    Member

    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.

  2. dokterbob commented on Aug 8, 2016

    @dokterbob
    ContributorAuthor

    @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?

  3. dokterbob commented on Aug 8, 2016

    @dokterbob
    ContributorAuthor

    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).

  4. whyrusleeping commented on Aug 8, 2016

    @whyrusleeping
    Member

    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.

  5. dokterbob commented on Aug 9, 2016

    @dokterbob
    ContributorAuthor
  6. changed the title [-]Expose unixfs object types in listings[/-] [+]Sort out/document listing commands[/+] on Aug 13, 2016
  7. changed the title [-]Sort out/document listing commands[/-] [+]Document listing commands[/+] on Aug 13, 2016
  8. changed the title [-]Document listing commands[/-] [+]Better document listing commands[/+] on Aug 13, 2016
  9. changed the title [-]Better document listing commands[/-] [+]Document listing commands better[/+] on Aug 13, 2016
  10. dokterbob commented on Aug 13, 2016

    @dokterbob
    ContributorAuthor

    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?

  11. added a commit that references this issue on Aug 13, 2016
    0aad342
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    help wantedSeeking public contribution on this issuekind/bugA bug in existing code (including security flaws)topic/docs-ipfsTopic docs-ipfs

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions