ipfs-inactive · alanshaw · Jun 19, 2018 · Jun 19, 2018
diff --git a/SPEC/FILES.md b/SPEC/FILES.md
@@ -2,29 +2,132 @@
 
 > The files API enables users to use the File System abstraction of IPFS.
 
-* [files.add](#filesadd)
-* [files.addReadableStream](#filesaddreadablestream)
-* [files.addPullStream](#filesaddpullstream)
-* [files.cat](#filescat)
-* [files.catReadableStream](#filescatreadablestream)
-* [files.catPullStream](#filescatpullstream)
-* [files.get](#filesget)
-* [files.getReadableStream](#filesgetreadablestream)
-* [files.getPullStream](#filesgetpullstream)
-* [ls](#ls)
-* [lsReadableStream](#lsreadablestream)
-* [lsPullStream](#lspullstream)
-* [files.cp](#filescp)
-* [files.mkdir](#filesmkdir)
-* [files.stat](#filesstat)
-* [files.rm](#filesrm)
-* [files.read](#filesread)
-* [files.readReadableStream](#filesreadreadablestream)
-* [files.readPullStream](#filesreadpullstream)
-* [files.write](#fileswrite)
-* [files.mv](#filesmv)
-* [files.flush](#filesflush)
-* [files.ls](#filesls)
+- [ls](#ls)
+- [lsReadableStream](#lsreadablestream)
+- [lsPullStream](#lspullstream)
+- files
+  - [files.add](#filesadd)
+  - [files.addReadableStream](#filesaddreadablestream)
+  - [files.addPullStream](#filesaddpullstream)
+  - [files.cat](#filescat)
+  - [files.catReadableStream](#filescatreadablestream)
+  - [files.catPullStream](#filescatpullstream)
+  - [files.get](#filesget)
+  - [files.getReadableStream](#filesgetreadablestream)
+  - [files.getPullStream](#filesgetpullstream)
+  - MFS (mutable file system)
+    - [files.cp](#filescp)
+    - [files.flush](#filesflush)
+    - [files.ls](#filesls)
+    - [files.mkdir](#filesmkdir)
+    - [files.mv](#filesmv)
+    - [files.read](#filesread)
+    - [files.readPullStream](#filesreadpullstream)
+    - [files.readReadableStream](#filesreadreadablestream)
+    - [files.rm](#filesrm)
+    - [files.stat](#filesstat)
+    - [files.write](#fileswrite)
+
+#### `ls`
+
+> Lists a directory from IPFS that is addressed by a valid IPFS Path.
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.ls(ipfsPath, [callback])
+
+> **Note:** ipfs.files.ls is currently only for MFS directories. The goal is to converge both functionality.
+
+ipfsPath can be of type:
+
+- [`cid`][cid] of type:
+  - [Buffer][b], the raw Buffer of the cid
+  - String, the base58 encoded version of the cid
+- String, including the ipfs handler, a cid and a path to traverse to, ie:
+  - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66'
+  - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
+  - 'QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
+
+`callback` must follow `function (err, files) {}` signature, where `err` is an error if the operation was not successful. `files` is an array containing objects of the following form:
+
+```js
+{
+  depth: 1,
+  name: 'alice.txt',
+  path: 'QmVvjDy7yF7hdnqE8Hrf4MHo5ABDtb5AbX6hWbD3Y42bXP/alice.txt',
+  size: 11696,
+  hash: 'QmZyUEQVuRK3XV7L9Dk26pg6RVSgaYkiSTEdnT2kZZdwoi',
+  type: 'file'
+}
+```
+
+If no `callback` is passed, a promise is returned.
+
+**Example:**
+
+```JavaScript
+const validCID = 'QmQ2r6iMNpky5f1m4cnm3Yqw8VSvjuKpTcK1X7dBR1LkJF'
+
+ipfs.ls(validCID, function (err, files) {
+  files.forEach((file) => {
+    console.log(file.path)
+  })
+})
+```
+
+A great source of [examples][] can be found in the tests for this API.
+
+#### `lsReadableStream`
+
+> Lists a directory from IPFS that is addressed by a valid IPFS Path. The list will be yielded as Readable Streams.
+
+##### `Go` **WIP**
+
+##### `JavaScript` - ipfs.lsReadableStream(ipfsPath) -> [Readable Stream][rs]
+
+> **Note:** ipfs.files.ls is currently only for MFS directories. The goal is to converge both functionality.
+
+ipfsPath can be of type:
+
+- [`cid`][cid] of type:
+  - [Buffer][b], the raw Buffer of the cid
+  - String, the base58 encoded version of the cid
+- String, including the ipfs handler, a cid and a path to traverse to, ie:
+  - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66'
+  - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
+  - 'QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
+
+It returns a [Readable Stream][rs] in [Object mode](https://nodejs.org/api/stream.html#stream_object_mode) that will yield objects of the form:
+
+```js
+{
+  depth: 1,
+  name: 'alice.txt',
+  path: 'QmVvjDy7yF7hdnqE8Hrf4MHo5ABDtb5AbX6hWbD3Y42bXP/alice.txt',
+  size: 11696,
+  hash: 'QmZyUEQVuRK3XV7L9Dk26pg6RVSgaYkiSTEdnT2kZZdwoi',
+  type: 'file'
+}
+```
+
+**Example:**
+
+```JavaScript
+const validCID = 'QmQ2r6iMNpky5f1m4cnm3Yqw8VSvjuKpTcK1X7dBR1LkJF'
+
+const stream = ipfs.lsReadableStream(validCID)
+
+stream.on('data', (file) => {
+  // write the file's path and contents to standard out
+  console.log(file.path)
+})
+```
+
+A great source of [examples][] can be found in the tests for this API.
+
+#### `lsPullStream`
+
+> Fetch a file or an entire directory tree from IPFS that is addressed by a valid IPFS Path. The files will be yielded through a Pull Stream.
 
 #### `files.add`
 
@@ -435,107 +538,6 @@ pull(
 A great source of [examples][] can be found in the tests for this API.
 
 
-#### `ls`
-
-> Lists a directory from IPFS that is addressed by a valid IPFS Path.
-
-##### `Go` **WIP**
-
-##### `JavaScript` - ipfs.ls(ipfsPath, [callback])
-
-> **Note:** ipfs.files.ls is currently only for MFS directories. The goal is to converge both functionality.
-
-ipfsPath can be of type:
-
-- [`cid`][cid] of type:
-  - [Buffer][b], the raw Buffer of the cid
-  - String, the base58 encoded version of the cid
-- String, including the ipfs handler, a cid and a path to traverse to, ie:
-  - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66'
-  - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
-  - 'QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
-
-`callback` must follow `function (err, files) {}` signature, where `err` is an error if the operation was not successful. `files` is an array containing objects of the following form:
-
-```js
-{
-  depth: 1,
-  name: 'alice.txt',
-  path: 'QmVvjDy7yF7hdnqE8Hrf4MHo5ABDtb5AbX6hWbD3Y42bXP/alice.txt',
-  size: 11696,
-  hash: 'QmZyUEQVuRK3XV7L9Dk26pg6RVSgaYkiSTEdnT2kZZdwoi',
-  type: 'file'
-}
-```
-
-If no `callback` is passed, a promise is returned.
-
-**Example:**
-
-```JavaScript
-const validCID = 'QmQ2r6iMNpky5f1m4cnm3Yqw8VSvjuKpTcK1X7dBR1LkJF'
-
-ipfs.ls(validCID, function (err, files) {
-  files.forEach((file) => {
-    console.log(file.path)
-  })
-})
-```
-
-A great source of [examples][] can be found in the tests for this API.
-
-#### `lsReadableStream`
-
-> Lists a directory from IPFS that is addressed by a valid IPFS Path. The list will be yielded as Readable Streams.
-
-##### `Go` **WIP**
-
-##### `JavaScript` - ipfs.lsReadableStream(ipfsPath) -> [Readable Stream][rs]
-
-> **Note:** ipfs.files.ls is currently only for MFS directories. The goal is to converge both functionality.
-
-ipfsPath can be of type:
-
-- [`cid`][cid] of type:
-  - [Buffer][b], the raw Buffer of the cid
-  - String, the base58 encoded version of the cid
-- String, including the ipfs handler, a cid and a path to traverse to, ie:
-  - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66'
-  - '/ipfs/QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
-  - 'QmXEmhrMpbVvTh61FNAxP9nU7ygVtyvZA8HZDUaqQCAb66/a.txt'
-
-It returns a [Readable Stream][rs] in [Object mode](https://nodejs.org/api/stream.html#stream_object_mode) that will yield objects of the form:
-
-```js
-{
-  depth: 1,
-  name: 'alice.txt',
-  path: 'QmVvjDy7yF7hdnqE8Hrf4MHo5ABDtb5AbX6hWbD3Y42bXP/alice.txt',
-  size: 11696,
-  hash: 'QmZyUEQVuRK3XV7L9Dk26pg6RVSgaYkiSTEdnT2kZZdwoi',
-  type: 'file'
-}
-```
-
-**Example:**
-
-```JavaScript
-const validCID = 'QmQ2r6iMNpky5f1m4cnm3Yqw8VSvjuKpTcK1X7dBR1LkJF'
-
-const stream = ipfs.lsReadableStream(validCID)
-
-stream.on('data', (file) => {
-  // write the file's path and contents to standard out
-  console.log(file.path)
-})
-```
-
-A great source of [examples][] can be found in the tests for this API.
-
-#### `lsPullStream`
-
-> Fetch a file or an entire directory tree from IPFS that is addressed by a valid IPFS Path. The files will be yielded through a Pull Stream.
-
 ##### `Go` **WIP**
 
 ##### `JavaScript` - ipfs.lsPullStream(ipfsPath) -> [Pull Stream][ps]