How does Files API - ipfs files command work.

[Kubuxu]

IPFS Files API allows to manipulate unixfs objects (current IPFS files and directories format) in manner similar to normal Unix commands.

How does it work:

IPFS Files API introduces virtual root directory. You can check it content with ipfs files ls /.
You can copy files and directories that were added to IFPS using ipfs files cp /ipfs/Qmc4xcnns2rA4akaWfGdzdaN8My1ES6zh7yddYZ5mo7n2U /greetings.

Then you can view content of that directory using ipfs files ls /greetings and read file in it using ipfs files read /greetings/greetings.md.

You can then modify the structure with different commands: ipfs files mv /greetings/greetings.md /greetings/greetings.txt, note that will change hash of the /greetings directory. You can check new hash using ipfs files stat --hash /greetings.

If you have any more questions, please ask.

[Ghoughpteighbteau]

So here's me playing around with this feature.

~ $ ipfs files ls
~ $ ipfs files cp /ipfs/QmQwAP9vFjbCtKvD8RkJdCvPHqLQjZfW7Mqbbqx18zd8j7 /examples
~ $ ipfs files ls -l 
examples    QmQwAP9vFjbCtKvD8RkJdCvPHqLQjZfW7Mqbbqx18zd8j7  0
~ $ ipfs files ls -l /examples | column -t
Makefile           QmVxEtpVTAjneTSC2vZukww5KfLMnHFsBA3XQZnMHNXXDf  157
api                QmavsNYkgNcrNGgcmF6iq1SrkaaFNJVzqEnfVfdixFpPsk  0
basics             QmYEcwYnCYb9CU6ipxRJvkFmBPwgRY4fD8eLLAj3rmetyi  0
bootstrap          QmXRv4gRdokiarChpxF33jr35b6rexADEcdkwoFqKBRhzZ  0
config             QmXhaJNHgzRaWqkdnmGJSPuxc12AueXeLda8F736MqPTbd  0
data               QmTitSFQFQeBMZRDsGEvzdNgPnwx7coBCQxEYvNzgWPkK8  0
git                Qmf6cuHtrDbqoKH2L8y9MtQUmGyNksR5RoKVNVvN23BG4G  0
graphmd            QmfT4cEw9zezKaV6wF9aELFtpuovxFCR8CXSkUb6enAgw8  0
init               QmTSE278Mb1dLXtco1wBbqaUCzD17hxRKGbqhZtUbNL3Vz  0
ipns               QmUTWHFReYWNf6DX2GKy1kGXFecxQPaLTyZjVf2zKr28xu  0
network            QmRPg57F8V46vvAGjdjARPtSMYj6wBicf482MJfen3M4LT  0
pinning            QmXQNjQFBv8DxjgW1artxcXdhReFoaGRxhKqYgiMGPJ9o1  0
published-version  QmPtqzMtd7ZLBWu9sF1xSUDfRZ6kkVnactBMKHdsMC1ZtJ  188
snapshots          QmYuo1vhfDNTAmTPakchttvamQj6aLFjv6J5oeUJZhC99M  0
videos             QmaJ8xTbRqTFBKEfePvL5tS3iAZJUMRWtUX9k8Pm9Sh8pT  0
websites           QmZdWW55p6YTkFnGZHUmdVZjVKaBA745FENzftoYdapU9g  0
~ $ ipfs files cp /ipfs/QmQwAP9vFjbCtKvD8RkJdCvPHqLQjZfW7Mqbbqx18zd8j7 /test
~ $ ipfs files ls -l 
examples    QmQwAP9vFjbCtKvD8RkJdCvPHqLQjZfW7Mqbbqx18zd8j7  0
test    QmQwAP9vFjbCtKvD8RkJdCvPHqLQjZfW7Mqbbqx18zd8j7  0
~ $ # gaaah, no columns....
~ $ ipfs files ls -l | column -t
examples  QmQwAP9vFjbCtKvD8RkJdCvPHqLQjZfW7Mqbbqx18zd8j7  0
test      QmQwAP9vFjbCtKvD8RkJdCvPHqLQjZfW7Mqbbqx18zd8j7  0
~ $ ipfs files rm -r /test
~ $ ipfs files mkdir /test
~ $ ipfs files cp /ipfs/QmQwAP9vFjbCtKvD8RkJdCvPHqLQjZfW7Mqbbqx18zd8j7 /test/otherExamples
~ $ ipfs files ls -l | column -t
examples  QmQwAP9vFjbCtKvD8RkJdCvPHqLQjZfW7Mqbbqx18zd8j7  0
test      QmdQ3wVuxPPSjbihiDKndwYBFQDtGWznEdmnjLEpdEphas  0
~ $ ipfs files ls -l /test | column -t
otherExamples  QmQwAP9vFjbCtKvD8RkJdCvPHqLQjZfW7Mqbbqx18zd8j7  0
~ $ ipfs files stat /
QmTffJW1tzPwikLeCAFw7t4DbZidVGwVM1oMs96PTy25tk
Size: 0
CumulativeSize: 794139
ChildBlocks: 2
Type: directory
~ $ ipfs files cp ./pic/dukesOfNyan.gif /test/dukesOfNyan.gif
Error: Paths must start with a leading slash.
~ $ # I expected that to work...
~ $ ipfs add ./pic/dukesOfNyan.gif 
added QmeFBEVocqUpuob62umabRuSXERGFwF6TVK3ZqBAdv3VjL dukesOfNyan.gif
~ $ ipfs files cp /ipfs/QmeFBEVocqUpuob62umabRuSXERGFwF6TVK3ZqBAdv3VjL /test/dukesOfNyan.gif
~ $ ipfs files ls -l /test | column -t
dukesOfNyan.gif  QmeFBEVocqUpuob62umabRuSXERGFwF6TVK3ZqBAdv3VjL  19411092
otherExamples    QmQwAP9vFjbCtKvD8RkJdCvPHqLQjZfW7Mqbbqx18zd8j7  0
~ $ ipfs files ls -l / | column -t
examples  QmQwAP9vFjbCtKvD8RkJdCvPHqLQjZfW7Mqbbqx18zd8j7  0
test      QmX8NbuNEEqqxDNU1GuXyQST83EpqRt3gQweZeAGzpJFGc  0

So a few questions. Is this meant as a convenient editor for adding IPFS directory objects?

Does this have an advantage over just editing a directory in the local file system and adding that?

I see root has a hash as well. If someone requests that hash, will I give it to them?

When I changed /test from being QmdQ3wVuxPPSjbihiDKndwYBFQDtGWznEdmnjLEpdEphas to QmX8NbuNEEqqxDNU1GuXyQST83EpqRt3gQweZeAGzpJFGc I noticed that the old versions of /test was still stored

~ $ ipfs object get /ipfs/QmdQ3wVuxPPSjbihiDKndwYBFQDtGWznEdmnjLEpdEphas
{"Links":[{"Name":"otherExamples","Hash":"QmQwAP9vFjbCtKvD8RkJdCvPHqLQjZfW7Mqbbqx18zd8j7","Size":396987}],"Data":"\u0008\u0001"}
~ $ ipfs object get /ipfs/QmX8NbuNEEqqxDNU1GuXyQST83EpqRt3gQweZeAGzpJFGc
{"Links":[{"Name":"dukesOfNyan.gif","Hash":"QmeFBEVocqUpuob62umabRuSXERGFwF6TVK3ZqBAdv3VjL","Size":19415747},{"Name":"otherExamples","Hash":"QmQwAP9vFjbCtKvD8RkJdCvPHqLQjZfW7Mqbbqx18zd8j7","Size":396987}],"Data":"\u0008\u0001"}

So each modification done in ipfs files is added to ipfs. Is that what the ipfs files flush command is for? To avoid constantly adding changes to ipfs?

I notice that entries into the files API are not pinned, should they be?

Finally I'm trying to get an overall sense of what this command is intended for long term. This kinda seems like a porcelain command, more than a plumbing. Long term, are we all going to have an IPFS 'drive', that our file browsers understand, where we organize the contents of IPFS?

[whyrusleeping]

Is this meant as a convenient editor for adding IPFS directory objects?

Yes, among other things

Does this have an advantage over just editing a directory in the local file system and adding that?

depends on what your usecase is, ipfs add actually uses this code under the hood, so performance should be identical

So each modification done in ipfs files is added to ipfs. Is that what the ipfs files flush command is for?

Each modification is stored unless you use the --flush=false option. If you set flush to false, it will not write intermediate objects out until you run a command on that branch with flush true, or you run ipfs files flush on the directory/object in question

I notice that entries into the files API are not pinned, should they be?

This one is tricky, and something we havent quite finished. Stuff in the files API are not currently pinned, and they should not be pinned recursively. The reason for this is because one use case we want to explicitly support is ipfs files cp /ipfs/Qm20TBDataSet /somewhere, and be able to operate on that dataset without pulling it entirely local. Towards this, we are going to implement a new pin type called 'best effort' that will keep what you have local, local. Until then, be wary running a gc if youre playing with the files api.

Long term, are we all going to have an IPFS 'drive', that our file browsers understand, where we organize the contents of IPFS?

Thats one idea :) And one i very much support

[madavieb]

This issue has been moved to https://discuss.ipfs.io/t/how-does-files-api-ipfs-files-command-work/344.

[jcaesar]

Just for future reference:

14:58:42 < JCaesar> voker57, so #143 (comment) has been implemented? Nice.
14:59:15 < voker57> JCaesar: yes

If I understood that correctly, you can safely remove the pin on a file you added after you've copied it with ipfs files.