Fix: innacuracies in MFS command documentation.
These also end up in API docs.
Hector Sanjuan committed
Mar 22, 2021 at 19:42 UTC
e7ddd3894ba2a0888ce38acf499b4a59883327f5
1 file changed
+26
-13
core/commands/files.go
+26
-13
@@ -43,16 +43,17 @@ The files facility interacts with MFS (Mutable File System). MFS acts as a
43
single, dynamic filesystem mount. MFS has a root CID that is transparently
44
updated when a change happens (and can be checked with "ipfs files stat /").
45
46
-All files and folders within MFS are respected and will not be cleaned up
47
-during garbage collections. MFS is independent from the list of pinned items
48
-("ipfs pin ls"). Calls to "ipfs pin add" and "ipfs pin rm" will add and remove
49
-pins independently of MFS. If MFS content that was
50
-additionally pinned is removed by calling "ipfs files rm", it will still
51
-remain pinned.
46
+All files and folders within MFS are respected and will not be deleted
47
+during garbage collections. However, a DAG may be referenced in MFS without
48
+being fully available locally (MFS content is lazy loaded when accessed).
49
+MFS is independent from the list of pinned items ("ipfs pin ls"). Calls to
50
+"ipfs pin add" and "ipfs pin rm" will add and remove pins independently of
51
+MFS. If MFS content that was additionally pinned is removed by calling
52
+"ipfs files rm", it will still remain pinned.
53
54
Content added with "ipfs add" (which by default also becomes pinned), is not
54
-added to MFS. Any content can be put into MFS with the command "ipfs files cp
55
-/ipfs/<cid> /some/path/".
55
+added to MFS. Any content can be lazily referenced from MFS with the command
56
+"ipfs files cp /ipfs/<cid> /some/path/" (see ipfs files cp --help).
57
58
59
NOTE:
@@ -321,11 +322,12 @@ func walkBlock(ctx context.Context, dagserv ipld.DAGService, nd ipld.Node) (bool
322
323
var filesCpCmd = &cmds.Command{
324
Helptext: cmds.HelpText{
324
- Tagline: "Copy any IPFS files and directories into MFS (or copy within MFS).",
325
+ Tagline: "Add references to IPFS files and directories in MFS (or copy within MFS).",
326
ShortDescription: `
326
-"ipfs files cp" can be used to copy any IPFS file or directory (usually in the
327
-form /ipfs/<CID>, but also any resolvable path), into the Mutable File System
328
-(MFS).
327
+"ipfs files cp" can be used to add references to any IPFS file or directory
328
+(usually in the form /ipfs/<CID>, but also any resolvable path) into MFS.
329
+This performs a lazy copy: the full DAG will not be fetched, only the root
330
+node being copied.
331
332
It can also be used to copy files within MFS, but in the case when an
333
IPFS-path matches an existing MFS path, the IPFS path wins.
@@ -337,6 +339,17 @@ $ ipfs add --quieter --pin=false <your file>
339
# ...
340
# ... outputs the root CID at the end
341
$ ipfs cp /ipfs/<CID> /your/desired/mfs/path
342
+
343
+If you wish to fully copy content from a different IPFS peer into MFS, do not
344
+forget to force IPFS to fetch to full DAG after doing the "cp" operation. i.e:
345
+
346
+$ ipfs cp /ipfs/<CID> /your/desired/mfs/path
347
+$ ipfs pin add <CID>
348
+
349
+The lazy-copy feature can also be used to protect partial DAG contents from
350
+garbage collection. i.e. adding the Wikipedia root to MFS would not download
351
+all the Wikipedia, but will any downloaded Wikipedia-DAG content from being
352
+GC'ed.
353
`,
354
},
355
Arguments: []cmds.Argument{
@@ -561,7 +574,7 @@ Examples:
574
575
$ ipfs files read /test/hello
576
hello
564
- `,
577
+ `,
578
},
579
580
Arguments: []cmds.Argument{