You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository was archived by the owner on Mar 10, 2020. It is now read-only.
@@ -590,28 +590,56 @@ A great source of [examples][] can be found in the tests for this API.
590
590
591
591
The Mutable File System (MFS) is a virtual file system on top of IPFS that exposes a Unix like API over a virtual directory. It enables users to write and read from paths without having to worry about updating the graph. It enables things like [ipfs-blob-store](https://github.com/ipfs/ipfs-blob-store) to exist.
##### `JavaScript` - ipfs.files.cp(...from, to, [options], [callback])
601
600
602
601
Where:
603
602
604
-
-`from` is the path of the source file to copy.
605
-
-`to` is the path of the destination file to copy to.
603
+
-`from` is the path(s) of the source to copy. It might be:
604
+
- An existing MFS path to a file or a directory (e.g. `/my-dir/my-file.txt`)
605
+
- An IPFS path (e.g. `/ipfs/QmWGeRAEgtsHW3ec7U4qW2CyVy7eA2mFRVbk1nb24jFyks`)
606
+
-`to` is the path of the destination to copy to
607
+
-`options` is an optional Object that might contain the following keys:
608
+
-`parents` is a Boolean value to decide whether or not to make the parent directories if they don't exist (default: false)
609
+
-`format` is what type of nodes to write any newly created directories as (default: `dag-pb`)
610
+
-`hashAlg` is which algorithm to use when creating CIDs for newly created directories (default: `sha2-256`)
611
+
-`flush` is a Boolean value to decide whether or not to immediately flush MFS changes to disk (default: true)
612
+
-`callback` is an optional function with the signature `function (error) {}`, where `error` may be an Error that occured if the operation was not successful
613
+
614
+
If `from` has multiple values then `to` must be a directory.
606
615
607
-
`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
616
+
If `from` has a single value and `to` exists and is a directory, `from` will be copied into `to`.
617
+
618
+
If `from` has a single value and `to` exists and is a file, `from` must be a file and the contents of `to` will be replaced with the contents of `from` otherwise an error will be returned.
619
+
620
+
If `from` is an IPFS path, and an MFS path exists with the same name, the IPFS path will be chosen.
608
621
609
622
If no `callback` is passed, a promise is returned.
-`options` is an optional Object that might contain the following keys:
633
-
-`parents` is a Boolean value to decide whether or not to make the parent directories if they don't exist.
634
-
635
-
`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
661
+
-`parents` is a Boolean value to decide whether or not to make the parent directories if they don't exist (default: false)
662
+
-`format` is what type of nodes to write any newly created directories as (default: `dag-pb`)
663
+
-`hashAlg` is which algorithm to use when creating CIDs for newly created directories (default: `sha2-256`)
664
+
-`flush` is a Boolean value to decide whether or not to immediately flush MFS changes to disk (default: true)
665
+
-`callback` is an optional function with the signature `function (error) {}`, where `error` may be an Error that occured if the operation was not successful
636
666
637
667
If no `callback` is passed, a promise is returned.
-`path` is the path to the file or directory to stat
660
690
-`options` is an optional Object that might contain the following keys:
661
-
-`hash` is a Boolean value to return only the hash.
662
-
-`size` is a Boolean value to return only the size.
663
-
-`withLocal` is a Boolean value to compute the amount of the dag that is local, and if possible the total size.
664
-
665
-
`callback` must follow the `function (err, stat) {}` signature, where `err` is an Error if the operation was not successful and `stat` is an Object with the following keys:
666
-
667
-
-`hash` is a string with the hash.
668
-
-`size` is an integer with the size in Bytes.
669
-
-`cumulativeSize` is an integer with the cumulative size in Bytes.
670
-
-`blocks` is an integer indicating the number of blocks.
671
-
-`type` is a string that can be either `directory` or `file`.
672
-
-`withLocality` is a boolean to indicate if locality information are present.
673
-
-`local` is a boolean to indicate if the queried dag is fully present locally.
674
-
-`sizeLocal` is an integer indicating the cumulative size of the data present locally.
675
-
691
+
-`hash` is a Boolean value to return only the hash (default: false)
692
+
-`size` is a Boolean value to return only the size (default: false)
693
+
-`withLocal` is a Boolean value to compute the amount of the dag that is local, and if possible the total size (default: false)
694
+
-`callback` is an optional function with the signature `function (error, stats) {}`, where `error` may be an Error that occured if the operation was not successful and `stats` is an Object with the following keys:
695
+
696
+
-`hash` is a string with the hash
697
+
-`size` is an integer with the file size in Bytes
698
+
-`cumulativeSize` is an integer with the size of the DAGNodes making up the file in Bytes
699
+
-`type` is a string that can be either `directory` or `file`
700
+
-`blocks` if `type` is `directory`, this is the number of files in the directory. If it is `file` it is the number of blocks that make up the file
701
+
-`withLocality` is a boolean to indicate if locality information are present
702
+
-`local` is a boolean to indicate if the queried dag is fully present locally
703
+
-`sizeLocal` is an integer indicating the cumulative size of the data present locally
676
704
677
705
If no `callback` is passed, a promise is returned.
-`options` is an optional Object that might contain the following keys:
707
-
-`recursive` is a Boolean value to decide whether or not to remove directories recursively.
708
-
709
-
`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
735
+
-`recursive` is a Boolean value to decide whether or not to remove directories recursively (default: false)
736
+
-`callback` is an optional function with the signature `function (error) {}`, where `error` may be an Error that occured if the operation was not successful
710
737
711
738
If no `callback` is passed, a promise is returned.
-`path` is the path of the file to read and must point to a file (and not a directory)
742
776
-`options` is an optional Object that might contain the following keys:
743
-
-`offset` is an Integer with the byte offset to begin reading from.
744
-
-`count` is an Integer with the maximum number of bytes to read.
745
-
746
-
`callback` must follow the `function (err, buf) {}` signature, where `err` is an Error if the operation was not successful and `buf` is a [`Buffer`][b] with the contents of `path`.
777
+
-`offset` is an Integer with the byte offset to begin reading from (default: 0)
778
+
-`length` is an Integer with the maximum number of bytes to read (default: Read to end of stream)
779
+
-`callback` is an optional function with the signature `function (error, buffer) {}`, where `error` may be an Error that occured if the operation was not successful and `buffer` is a [`Buffer`][b] with the contents of `path`
747
780
748
781
If no `callback` is passed, a promise is returned.
749
782
783
+
N.b. this method is likely to result in high memory usage, you should use [files.readReadableStream](#filesreadreadablestream) or [files.readPullStream](#filesreadpullstream) instead where possible.
- a [`Blob`][blob] (caveat: will only work in the browser)
831
866
- a string path to a file (caveat: will only work in Node.js)
832
867
-`options` is an optional Object that might contain the following keys:
833
-
-`offset` is an Integer with the byte offset to begin writing at.
834
-
-`create` is a Boolean to indicate to create the file if it doesn't exist.
835
-
-`truncate` is a Boolean to indicate if the file should be truncated to size 0 before writing.
836
-
-`count` is an Integer with the maximum number of bytes to read.
837
-
838
-
`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
868
+
-`offset` is an Integer with the byte offset to begin writing at (default: 0)
869
+
-`create` is a Boolean to indicate to create the file if it doesn't exist (default: false)
870
+
-`truncate` is a Boolean to indicate if the file should be truncated after writing all the bytes from `content` (default: false)
871
+
-`length` is an Integer with the maximum number of bytes to read (default: Read all bytes from `content`)
872
+
-`callback` is an optional function with the signature `function (error) {}`, where `error` may be an Error that occured if the operation was not successful
839
873
840
874
If no `callback` is passed, a promise is returned.
##### `JavaScript` - ipfs.files.mv(...from, to, [options], [callback])
857
891
858
892
Where:
859
893
860
-
-`from` is the path of the source file to move.
861
-
-`to` is the path of the destination file to move to.
894
+
-`from` is the path(s) of the source to move
895
+
-`to` is the path of the destination to move to
896
+
-`options` is an optional Object that might contain the following keys:
897
+
-`parents` is a Boolean value to decide whether or not to make the parent directories if they don't exist (default: false)
898
+
-`format` is what type of nodes to write any newly created directories as (default: `dag-pb`)
899
+
-`hashAlg` is which algorithm to use when creating CIDs for newly created directories (default: `sha2-256`)
900
+
-`flush` is a Boolean value to decide whether or not to immediately flush MFS changes to disk (default: true)
901
+
-`callback` is an optional function with the signature `function (error) {}`, where `error` may be an Error that occured if the operation was not successful
902
+
903
+
If `from` has multiple values then `to` must be a directory.
904
+
905
+
If `from` has a single value and `to` exists and is a directory, `from` will be moved into `to`.
906
+
907
+
If `from` has a single value and `to` exists and is a file, `from` must be a file and the contents of `to` will be replaced with the contents of `from` otherwise an error will be returned.
862
908
863
-
`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
909
+
If `from` is an IPFS path, and an MFS path exists with the same name, the IPFS path will be chosen.
910
+
911
+
All values of `from` will be removed after the operation is complete, unless they are an IPFS path.
864
912
865
913
If no `callback` is passed, a promise is returned.
`callback` must follow the `function (err) {}` signature, where `err` is an Error if the operation was not successful.
947
+
-`paths` are an optional string paths to flush (default: `/`)
948
+
-`callback` is an optional function with the signature `function (error) {}`, where `error` may be an Error that occured if the operation was not successful
890
949
891
950
If no `callback` is passed, a promise is returned.
-`path` is the path to show listing for. Defaults to `/`.
914
-
-`options` is an optional Object that might contain the following keys:
915
-
-`l` is a Boolean value o use long listing format.
916
-
917
-
`callback` must follow `function (err, files) {}` signature, where `err` is an error if the operation was not successful. `files` is an array containing Objects that contain the following keys:
972
+
-`path` is an optional string to show listing for (default: `/`)
973
+
-`callback` is an optional function with the signature `function (error, files) {}`, where `error` may be an Error that occured if the operation was not successful and `files` is an array containing Objects that contain the following keys:
918
974
919
-
-`name` which is the file's name.
920
-
-`type` which i the object's type (`directory` or `file`).
921
-
-`size` the size of the file in bytes.
922
-
-`hash` the hash of the file.
975
+
-`name` which is the file's name
976
+
-`type` which i the object's type (`directory` or `file`)
977
+
-`size` the size of the file in bytes
978
+
-`hash` the hash of the file
923
979
924
980
If no `callback` is passed, a promise is returned.
0 commit comments