Sort out listing commands

[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): P2

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

This obviously needs to be sorted out. Judging from the descriptions it seems there is an overlap between the ls and object ls but I'm not sure if they are. In the case of file ls versus files ls this is definitly not the case as file ls takes hases as arguments whereas files ls only works within a unixfs root.

In any case it seems worthwhile to unify these. So the question is: how to go about this? What functionality do we need and how might it be split up?

As per #3057 (comment), this ticket could be split up in a bunch more specific issues:

• Improving command descriptions Document listing commands better #3057
• Fully migrate functionality of ipfs file ls to ipfs ls Migrate full functionality of ipfs file ls to ipfs ls #3081

[whyrusleeping]

see my comment at: #3057 (comment)

[dokterbob]

Example output of different commands:

$ ipfs ls --enc=json <hash>

{
    "Objects": [{
        "Hash": "<hash1>",
        "Links": [{
            "Name": "Books",
            "Hash": "<hash2>",
            "Size": 1838776295,
            "Type": 1
        }]
    }]
}

$ ipfs file ls --enc=json <hash>

{
    "Arguments": {
        "<hash1>": "<hash1>"
    },
    "Objects": {
        "<hash1>": {
            "Hash": "<hash1>",
            "Size": 0,
            "Type": "Directory",
            "Links": [{
                "Name": "Books",
                "Hash": "<hash2>",
                "Size": 1838776295,
                "Type": "Directory"
            }]
        }
    }
}

$ ipfs object links --enc=json <hash>

{
    "Hash": "<hash1>",
    "Links": [{
        "Name": "Books",
        "Hash": "<hash2>",
        "Size": 1838776295
    }]
}

$ ipfs files ls --enc=json <path>

{
    "Entries": [{
        "Name": "Books",
        "Type": 0,
        "Size": 0,
        "Hash": ""
    }]
}

[dokterbob]

Several observation relating to the differences in commands

• file ls seems the only way to determine the type of the current object
• files stat will also return the type of the current file, but has been constructed to only work on 'local' paths
• file ls returns 0 as filesize for the current object, see file ls command returning 0 size on requested hash #3232
• Both file ls and files ls display the type, however ipfs ls returns a numeric type, which is not self-descriptive at all.

Some questions/suggestions

1. Do we need listing commands to return information about the current object (the object being listed)? (This might make sense as we've basically just fetched this information in the process of listing.)
2. Wouldn't it make sense to enable files commands for hashes as well as paths? (i.e. /ipfs/<hash> as well as /Books) If not, we might need a secondary ipfs stat command with similar functionality in order to find out whether some object is a file or a directory.
3. Do we want more verbose information returned ("Directory") instead of more dense ("2") information returned in API calls?

[aschmahmann]

Closing and we should track in the meta issue