Skip to content
This repository was archived by the owner on Mar 10, 2020. It is now read-only.

Commit 510516a

Browse files
achingbrainachingbrain
authored
Merge pull request #277 from ipfs/files-spec-update
docs: remove array arguments and document missing options
2 parents 0a62f02 + c269bc3 commit 510516a

File tree

1 file changed

+128
-72
lines changed

1 file changed

+128
-72
lines changed

‎SPEC/FILES.md

Lines changed: 128 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -590,28 +590,56 @@ A great source of [examples][] can be found in the tests for this API.
590590

591591
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.
592592

593-
594593
#### `files.cp`
595594

596595
> Copy files.
597596
598597
##### `Go` **WIP**
599598

600-
##### `JavaScript` - ipfs.files.cp([from, to], [callback])
599+
##### `JavaScript` - ipfs.files.cp(...from, to, [options], [callback])
601600

602601
Where:
603602

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.
606615

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.
608621

609622
If no `callback` is passed, a promise is returned.
610623

611624
**Example:**
612625

613626
```JavaScript
614-
ipfs.files.cp(['/src-file', '/dst-file'], (err) => {
627+
// To copy a file
628+
ipfs.files.cp('/src-file', '/dst-file', (err) => {
629+
if (err) {
630+
console.error(err)
631+
}
632+
})
633+
634+
// To copy a directory
635+
ipfs.files.cp('/src-dir', '/dst-dir', (err) => {
636+
if (err) {
637+
console.error(err)
638+
}
639+
})
640+
641+
// To copy multiple files to a directory
642+
ipfs.files.cp('/src-file1', '/src-file2', '/dst-dir', (err) => {
615643
if (err) {
616644
console.error(err)
617645
}
@@ -624,15 +652,17 @@ ipfs.files.cp(['/src-file', '/dst-file'], (err) => {
624652
625653
##### `Go` **WIP**
626654

627-
##### `JavaScript` - ipfs.files.mkdir(path, [options, callback])
655+
##### `JavaScript` - ipfs.files.mkdir(path, [options], [callback])
628656

629657
Where:
630658

631-
- `path` is the path to the directory to make.
659+
- `path` is the path to the directory to make
632660
- `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
636666

637667
If no `callback` is passed, a promise is returned.
638668

@@ -652,27 +682,25 @@ ipfs.files.mkdir('/my/beautiful/directory', (err) => {
652682
653683
##### `Go` **WIP**
654684

655-
##### `JavaScript` - ipfs.files.stat(path, [options, callback])
685+
##### `JavaScript` - ipfs.files.stat(path, [options], [callback])
656686

657687
Where:
658688

659-
- `path` is the path to the directory to stat.
689+
- `path` is the path to the file or directory to stat
660690
- `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
676704

677705
If no `callback` is passed, a promise is returned.
678706

@@ -698,15 +726,14 @@ ipfs.files.stat('/file.txt', (err, stats) => {
698726
699727
##### `Go` **WIP**
700728

701-
##### `JavaScript` - ipfs.files.rm(path, [options, callback])
729+
##### `JavaScript` - ipfs.files.rm(...paths, [options], [callback])
702730

703731
Where:
704732

705-
- `path` is the path of the file to remove.
733+
- `paths` are one or more paths to remove
706734
- `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
710737

711738
If no `callback` is passed, a promise is returned.
712739

@@ -720,6 +747,13 @@ ipfs.files.rm('/my/beautiful/file.txt', (err) => {
720747
}
721748
})
722749

750+
// To remove multiple files
751+
ipfs.files.rm('/my/beautiful/file.txt', '/my/other/file.txt', (err) => {
752+
if (err) {
753+
console.error(err)
754+
}
755+
})
756+
723757
// To remove a directory
724758
ipfs.files.rm('/my/beautiful/directory', { recursive: true }, (err) => {
725759
if (err) {
@@ -738,19 +772,20 @@ ipfs.files.rm('/my/beautiful/directory', { recursive: true }, (err) => {
738772

739773
Where:
740774

741-
- `path` is the path of the file to read.
775+
- `path` is the path of the file to read and must point to a file (and not a directory)
742776
- `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`
747780

748781
If no `callback` is passed, a promise is returned.
749782

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.
784+
750785
**Example:**
751786

752787
```JavaScript
753-
ipfs.files.read('/hello-world', (err, buf) => {
788+
ipfs.files.read('/hello-world', (error, buf) => {
754789
console.log(buf.toString('utf8'))
755790
})
756791

@@ -767,10 +802,10 @@ ipfs.files.read('/hello-world', (err, buf) => {
767802

768803
Where:
769804

770-
- `path` is the path of the file to read.
805+
- `path` is the path of the file to read and must point to a file (and not a directory)
771806
- `options` is an optional Object that might contain the following keys:
772-
- `offset` is an Integer with the byte offset to begin reading from.
773-
- `count` is an Integer with the maximum number of bytes to read.
807+
- `offset` is an Integer with the byte offset to begin reading from (default: 0)
808+
- `length` is an Integer with the maximum number of bytes to read (default: Read to end of stream)
774809

775810
Returns a [`ReadableStream`][rs] with the contents of `path`.
776811

@@ -793,10 +828,10 @@ stream.on('data', (buf) => console.log(buf.toString('utf8')))
793828

794829
Where:
795830

796-
- `path` is the path of the file to read.
831+
- `path` is the path of the file to read and must point to a file (and not a directory)
797832
- `options` is an optional Object that might contain the following keys:
798-
- `offset` is an Integer with the byte offset to begin reading from.
799-
- `count` is an Integer with the maximum number of bytes to read.
833+
- `offset` is an Integer with the byte offset to begin reading from (default: 0)
834+
- `length` is an Integer with the maximum number of bytes to read (default: Read to end of stream)
800835

801836
Returns a [`PullStream`][ps] with the contents of `path`.
802837

@@ -818,24 +853,23 @@ pull(
818853
819854
##### `Go` **WIP**
820855

821-
##### `JavaScript` - ipfs.files.write(path, content, [options, callback])
856+
##### `JavaScript` - ipfs.files.write(path, content, [options], [callback])
822857

823858
Where:
824859

825-
- `path` is the path of the file to write.
860+
- `path` is the path of the file to write
826861
- `content` can be:
827862
- a [`Buffer`][b]
828863
- a [`PullStream`][ps]
829864
- a [`ReadableStream`][rs]
830865
- a [`Blob`][blob] (caveat: will only work in the browser)
831866
- a string path to a file (caveat: will only work in Node.js)
832867
- `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
839873

840874
If no `callback` is passed, a promise is returned.
841875

@@ -853,21 +887,47 @@ ipfs.files.write('/hello-world', Buffer.from('Hello, world!'), (err) => {
853887
854888
##### `Go` **WIP**
855889

856-
##### `JavaScript` - ipfs.files.mv([from, to], [callback])
890+
##### `JavaScript` - ipfs.files.mv(...from, to, [options], [callback])
857891

858892
Where:
859893

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.
862908

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.
864912

865913
If no `callback` is passed, a promise is returned.
866914

867915
**Example:**
868916

869917
```JavaScript
870-
ipfs.files.mv(['/src-file', '/dst-file'], (err) => {
918+
ipfs.files.mv('/src-file', '/dst-file', (err) => {
919+
if (err) {
920+
console.error(err)
921+
}
922+
})
923+
924+
ipfs.files.mv('/src-dir', '/dst-dir', (err) => {
925+
if (err) {
926+
console.error(err)
927+
}
928+
})
929+
930+
ipfs.files.mv('/src-file1', '/src-file2', '/dst-dir', (err) => {
871931
if (err) {
872932
console.error(err)
873933
}
@@ -880,13 +940,12 @@ ipfs.files.mv(['/src-file', '/dst-file'], (err) => {
880940
881941
##### `Go` **WIP**
882942

883-
##### `JavaScript` - ipfs.files.flush([path, callback])
943+
##### `JavaScript` - ipfs.files.flush([...paths], [callback])
884944

885945
Where:
886946

887-
- `path` is the path to flush. Default is `/`.
888-
889-
`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
890949

891950
If no `callback` is passed, a promise is returned.
892951

@@ -906,20 +965,17 @@ ipfs.files.flush('/', (err) => {
906965
907966
##### `Go` **WIP**
908967

909-
##### `JavaScript` - ipfs.files.ls([path, options, callback])
968+
##### `JavaScript` - ipfs.files.ls([path], [callback])
910969

911970
Where:
912971

913-
- `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:
918974

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
923979

924980
If no `callback` is passed, a promise is returned.
925981

0 commit comments

Comments
 (0)