Get to understand more on adding, pinning and retrieving files

Hi guys, hope you guys are having a good day.

I have several questions. Hope you guys can help me to understand more how IPFS & IPFS cluster works :slight_smile:

1. recursive param of IPFS cluster /add API
I tried using both recursive=false and recursive=true when adding files through IPFS cluster /add endpoint and did not notice any difference in the pinning results (inspecting using ipfs pin ls).
Both have the results of the root CID being pinned recursively and its children being pinned indirectly.
So what is the different when using different value for recursive?

2. What is the actual meaning of recursive pinning?
As far as I understand, IPFS can compute the content based on the root CID. So do we really need to persist the child CIDs by pinning them? If a child cid gets garbage collected, can IPFS still compute the whole content using only the root ID?

Really appreciate any comment. Many thanks!

Recursive is a client-side option that dictates if the client should recursively add folders. In fact it is more like a safeguard so that you don’t add a folder when you are expecting to add a file.

For consistency/simplicity reasons it is part of the API params, but I don’t think it is an option used server-side at all, iirc.

To not mix with the above, as it is a different option, there are different modes of pinning: recursive or direct.

When GC happens, the blocks that are referenced by direct-pins are added to the keep-list. The blocks that are referenced by recursive-pins, along with their children, and the children of their children are added by the keep-list.

If you have something with many blocks (i.e. added a directory with files), and you pin the root CID in “direct” mode only, and you GC, IPFS will still have the root-block, but not anything below. So the root block will point to other blocks that are unavailable, locally at least.

Thanks for the clarification @hector.

So in this case, assume that no other nodes have a copy of such the content (in a way that can form a full tree), can the content still be fully retrieved even when the root block points to nothing?

No, it cannot, since the other blocks are deleted.

Thanks a lot Hector. Got the idea :+1: