Document the code flow of adding a file using ipfs add <file> command.

[nitishm]

PH to capture the life of the ipfs add <file> command from the CLI, to highlight :

• The invocations (from addCmd() to adder.AddAllAndPin())
• Interfaces and their (various) implementations like UnixfsAPI interface / implementation.
• The objects created and used to add the file to the FS.

[nitishm]

#5052

[schomatis]

@schomatis How can I tag my issue #5858 with the milestone ?

Oh, you can't, sorry, forgot about the permissions bla blah, I'll take care of that.

[schomatis]

As a first step I would skip all the options handling code in the CoreAPI and go directly to AddAllAndPin() (assuming the default or most common used options).

[nitishm]

@schomatis Ok that makes it much easier to capture.

[schomatis]

Also some of the documentation of #5081 and related (now a bit outdated) may contain useful information overlapping with this.

[nitishm]

Also some of the documentation of #5081 and related (now a bit outdated) may contain useful information overlapping with this.

Will make sure I capture all the important contents from the issue.

[nitishm]

@schomatis Quick question to resolve my confusion. How is it that if I add a file through the WebGUI I can list it using ipfs files ls but I do the same with ipfs add <file> --pin=true I cannot see it using ipfs files ls. Is there some concept that I might have overlooked ?

[schomatis]

Excellent question!

I don't have time at the moment for the full answer but the summary would be: the are two layers of abstraction at play here, when I add a file with ipfs add I'm at the DAG/UnixFS layers, IPFS chunks it and organizes it in a DAG using the CID of the root to reference the file, its there, you can list it with ipfs ls (which looks for it in the DAG layer). On top of that you have MFS, which create a virtual filesystem where you can organize UnixFS files with more flexibility, you manipulate that with ipfs files (which I'm realizing now it's a rather unfortunate name, because we're not talking about any file but rather only the files in this special filesystem, it should be called the ipfs mfs command). So you add a file first to the "IPFS world" where you formatted in a DAG with UnixFS attributes to keep the file metadata, and then you can add that file to your local MFS with ipfs files cp which brings it into your filesystem.

Everything is a UnixFS file, but not every UnixFS file you add lives in your MFS.

(please ping me later about this subject for a more detailed answer and lets get this in https://github.com/ipfs/docs/issues/133, I can't begin to tell you how useful this question is, this is something I also wondered about when I started with this, and then I forgot about it)

[nitishm]

@schomatis I have a short writeup in Markdown format ready for this task. Where do you want me to add it ? Should this go in the ipfs/docs, under contents ?

[schomatis]

Open a PR in this repo (in the docs dir) or just paste it at the top of this issue.

[nitishm]

#5864 Created a PR in the docs directory.