Why is ipfs files ls being deprecated?

dadepo · May 2, 2020, 8:55am

I was reading through the cli reference here and I noticed the statement about ipfs file ls being deprecated:

This functionality is deprecated, and will be removed in future versions. If
possible, please use ‘ipfs ls’ instead

But from reading about Mutable File System (MFS) here it is stated that:

MFS is accessed through the files commands in the IPFS CLI and API

If listing via ls is part of the functionality of MFS, won’t it be consistent to keep it as subcommand of ipfs file?

achingbrain · May 2, 2020, 9:38am

The commands are different:

ipfs file ls (and ipfs ls) works on IPFS paths - e.g /ipfs/Qmfoo or /ipfs/Qmfoo/some/dir

ipfs files ls works on MFS paths e.g. /path/in/my/mfs

The confusion is part of why it’s deprecated.

dadepo · May 2, 2020, 9:58am

Thanks for the response. But a little more clarification would be needed as I find what you said a bit confusing still. I illustrate:

The above statement appears contradictory…unless you mean to say that:

ipfs files ls works both on IPFS paths and MFS paths while ipfs ls works only on IPFS paths.

Or maybe there is an unintended typo in there that leads to the apparent contradiction?

Also while we are at it, this is the first time I see a clear distinction been made between IPFS path and MFS path. Want to shed more light on that? Or point to resources that does? Saving me a couple of googling time

dadepo · May 2, 2020, 10:05am

oh my! The plot thickens. Just seeing there is: ipfs ls, ipfs files ls, and ipfs file ls…not sure yet why there is ipfs file and ipfs files…

achingbrain · May 2, 2020, 10:31am

ipfs file ls is the same as ipfs ls.

ipfs ls works on IPFS paths.

An IPFS path is a CID that resolves to a DAG that represents a directory (e.g. /ipfs/Qmfoo) or a subdirectory (e.g. /ipfs/Qmfoo/subdir)

IPFS paths are not MFS paths.

MFS paths are used by the ipfs files ... commands and look like traditional Unix paths but apply to a DAG in your repo.

Please see the IPFS primer for more information: https://dweb-primer.ipfs.io and the docs https://docs-beta.ipfs.io

dadepo · May 2, 2020, 10:43am

Not sure about this though. Here are some output from my terminal that shows they are not 100% same

$ ./ipfs ls QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB

while

$ ./ipfs file ls QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB
QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB

With a data that is way larger than 256K

$ ./ipfs ls QmPZYifeFZFbPFTSt1iDg6TM9vXEPUSYTwtC7jMPnrdz53
QmViHZnWRf45Lhnd8JHwtp7bZRtt3ePWcVa4vK7jyL7jeq 262144 
QmfAgqGwwKSNVusRbNMnStc9Te68M9zi9pKXCbNQT8p69s 262144 
Qmd5Y6WgLHwLddck34NXwMUkFQkPg9A6Re7RYmMF3cCrU5 262144 
Qmc6FWE6bagz2rC5QX8A2CKDpKwiUQshSf5rdVEQpRebKR 262144
...
...
...

while 

$ ./ipfs file ls QmPZYifeFZFbPFTSt1iDg6TM9vXEPUSYTwtC7jMPnrdz53
QmPZYifeFZFbPFTSt1iDg6TM9vXEPUSYTwtC7jMPnrdz53

These two commands show different behaviour.

achingbrain · May 2, 2020, 10:51am

Heh, well, the intention behind the commands is the same, but the implementation differs:

$ ipfs ls --help
USAGE
  ipfs ls <ipfs-path>... - List directory contents for Unix filesystem objects.

$ ipfs file ls --help
USAGE
  ipfs file ls <ipfs-path>... - List directory contents for Unix filesystem objects.

dadepo · May 2, 2020, 10:53am

Yeah, which is why it all feels confusing. I read the cli help text, execute the commands and I see different things…For example more outputs showing their differences:

./ipfs file ls QmQPeNsJPyVWPFDVHb77w8G42Fvo15z4bG2X8D2GhfbSXc/
about
contact
help
ping
quick-start
readme
security-notes

while

./ipfs ls QmQPeNsJPyVWPFDVHb77w8G42Fvo15z4bG2X8D2GhfbSXc/
QmQy6xmJhrcC5QLboAcGFcAE1tC8CrwDVkrHdEYJkLscrQ 1681 about
QmYCvbfNbCwFR45HiNP45rwJgvatpiW38D961L5qAhUM5Y 189  contact
QmU5k7ter3RdjZXu3sHghsga1UQtrztnQxmTL22nPnsu3g 311  help
QmejvEPop4D7YUadeGqYWmZxHhLc4JBUCzJJHWMzdcMe2y 4    ping
QmQGiYLVAdSHJQKYFRTJZMG4BXBHqKperaZtyKGmCRLmsF 1681 quick-start
QmPZ9gcCEpqKTo6aq61g2nXGUhM4iCL3ewB6LDXZCtioEB 1091 readme
QmQ5vhrL7uv6tuoN9KeVBwd4PwfQkXdVVmDLUZuTNxqgvm 1162 security-notes

/ipfs file ls seems to drop some of the ipfs specific info, but ipfs ls does not.

dadepo · May 2, 2020, 11:27am

Talking about intentions, this is the conclusion I am reaching after poking around a bit more and reading more cli help text:

Apparently mfs is 100% distinct and separate thing and it differs from the other file operations I have been seeing and running. These portion from the help text of ipfs files made it clear:

Content added with “ipfs add” (which by default also becomes pinned), is not
added to MFS. Any content can be put into MFS with the command “ipfs files cp
/ipfs/ /some/path/”

So ipfs ls and ipfs file ls are supposed to be the same (although they show slightly different behaviour in reality). While ipfs files commands deal in the realm of MFS.

This is also basically what you explained here

I think it is less confusing now. Thanks @achingbrain.

Now with this clarification, I can see how the title I used for this thread is wrong:

Why is ipfs files ls being deprecated?

It is not ipfs file*s* ls that is being deprecated (which exist within MFS), but ipfs file ls that is being deprecated since it should be more or less the same as ipfs ls - even though in reality both commands show slightly different behaviours.