update docs with new beta apis and output and implement dat status

beta-cli-api.md

@@ -14,6 +14,7 @@ This is the proposed CLI API for our Beta release. Please leave feedback [in thi
  - [dat checkout](#dat-checkout)
  - [dat diff](#dat-diff)
  - [dat merge](#dat-merge)
  - [dat forks](#dat-forks)
- [dataset commands](#dataset-commands)
  - [dat import](#dat-import)
  - [dat export](#dat-export)
@@ -71,7 +72,7 @@ All commands have these options:

- `path`/`p` - specify the path to the dat directory that the command should use. Default is current working directory
- `help`/`h` (boolean) - pass this option to show the help for a command.
- `log` (default 'text') - set this to 'json' to change the response format logging for status/response messages to JSON for easy parsing.
- `json` - set this to true to change all output to JSON for easy parsing.
- `checkout` - the version hash to use when retrieving data for a command.

Example output:
@@ -82,7 +83,7 @@ usage: dat <command(s)> [-flag] [--key value]

commands:
  init      initialize a new dat in a directory
  checkout  dat will operate at a particular head
  checkout  dat will operate at a particular fork
  add       import a file into dat
  push      push data to a remote dat
  ... etc
@@ -119,7 +120,7 @@ Example output:
```
$ dat status
Current version is now 8eaf3b0739d32849687a544efae8487b5b05df52
438 keys, 32 files, 3 commits, 143 Mb total
438 keys, 32 files, 3 versions, 143 Mb total
Last updated 3 seconds ago
```

@@ -173,7 +174,7 @@ Example output:
```
$ dat pull ssh://192.168.0.5:~/data
Pulled 823 changes (93.88 Mb, 3.4 Mb/s).
Pull completed successfully.
Pull completed successfully, you now have 2 forks.
Current version is now b04adb64fdf2203
```

@@ -206,9 +207,16 @@ If `<version hash>` is specified as the first positional argument then the indiv
Example output:

```
$ dat log --limit=2
{ "change": 1, "version": "6bdd624ae6f9ddb96069e04fc030c6e964e77ac7", links: [...], "puts": 12, "deletes": 3, "date": "2015..."}
{ "change": 2, "version": "7b13de1bd942a0cbfc2721d9e0b9a4fa5a076517", links: [...], "puts": 0, "deletes": 2, "date": "2015..."}
$ dat log --limit=1
Version: 6bdd624ae6f9ddb96069e04fc030c6e964e77ac7 [+12, -3]
Date:    April 15th 2015, 7:30PM PST

  added cool csv
```

```
$ dat log --limit=1 --json
{ "change": 1, "version": "6bdd624ae6f9ddb96069e04fc030c6e964e77ac7", links: [...], "puts": 12, "deletes": 3, "date": "2015...", "message": "added cool csv"}
```

`Links` is a list of older versions that are referenced from this current version (forms a directed acyclic graph if drawn).
@@ -219,10 +227,10 @@ $ dat log --limit=2
Non-destructive rollback state to a hash in the past

```bash
dat checkout <commit-hash>
dat checkout <version-hash>
```

Check out latest commit on default branch
Check out latest version on default branch

```bash
dat checkout latest
@@ -248,9 +256,22 @@ If the same key is in both versions but the values differ, a diff object will be
Example output:

```
$ dat diff --pretty 163c6089c3477eecfa42420b4249f481b61c30b63071079e51cb052451862502 64843f272df9526fb04adb64fdf220330c9a29a8104c9ae4dead6b0aab5748e3
$ dat diff 64843f272df
Diff between "Imported csv" and "Re-imported edited csv"
  ? "first":"Max" -> "MAX"
  - "hey": "deleted"
  + "foo": "bar"
Diff between "Initial data import" and "Re-imported edited csv"
  ? "first":"Bob" -> "BOB"
  - "hey": "deleted"
  + "foo": "bar"
```

```
$ dat diff --pretty --json 64843f272df9526fb04adb64fdf220330c9a29a8104c9ae4dead6b0aab5748e3
{
  "key": "1",
  "forks": ["163c6089c3477eecfa42420b4249f481b61c30b63071079e51cb052451862502", "64843f272df9526fb04adb64fdf220330c9a29a8104c9ae4dead6b0aab5748e3" ]
  "versions": [
    {
      "type": "put",
@@ -260,8 +281,7 @@ $ dat diff --pretty 163c6089c3477eecfa42420b4249f481b61c30b63071079e51cb05245186
      "value": {
        "key": "1",
        "name": "Max"
      },
      "checkout": "163c6089c3477eecfa42420b4249f481b61c30b63071079e51cb052451862502"
      }
    },
    {
      "type": "put",
@@ -271,51 +291,56 @@ $ dat diff --pretty 163c6089c3477eecfa42420b4249f481b61c30b63071079e51cb05245186
      "value": {
        "key": "1",
        "name": "MAX"
      },
      "checkout": "64843f272df9526fb04adb64fdf220330c9a29a8104c9ae4dead6b0aab5748e3"
      }
    }
  ]
}
<... etc for each key in the diff>
```

### dat merge

Merge two checkouts of a dataset into a single checkout. Uses [knead](http://github.com/karissa/knead) as default merge tool for now.
Merges two forks.

```
dat merge <versionA> <versionB>
dat merge <forkA> <forkB>
```

#### Options
`--merge-tool`: run the given merge tool to assist in resolving conflicts manually.

`-` for <file>: receive resolved changes on stdin
- `-` for <file>: receive resolved changes on stdin
- `left`: pick the left side as the winner
- `right`: pick the right side as the winner
- `yolo`: pick random side for each key


#### Resolutions from file
Example output:

A `dat merge` receives a stream of changes that will be applied to resolve conflicts between two versions.

$ dat merge

Merging from a file:

```
$ cat resolutions.json | dat merge ab3234dfe5 bdc3ae23cef -
$ dat merge resolutions.json
Changes resolved successfully.
Current version is now b04adb64fdf2203
```

#### Merge tools
Merging as a stream using `dat diff`:

```
$ dat merge ab3234dfe5 bdc3ae23cef --merge-tool="my-merge-tool.sh"
$ dat diff ab3234dfe5 bdc3ae23cef | <tool> | dat merge -
Changes resolved successfully.
Current version is now b04adb64fdf2203
Current version is now 98v8catb4bvcddf
```

In this example, the `<merge-function/tool>` decides which change to keep between the versions suppled in a `dat diff`, outputting the json for each kept change to stdout.
Merging two forks by picking one side:

```
$ dat diff ab3234dfe5 bdc3ae23cef | <merge-function/tool> | dat merge ab3234dfe5 bdc3ae23cef -
$ dat merge ab3234dfe5 bdc3ae23cef --left
Changes resolved successfully.
Current version is now b04adb64fdf2203
Current version is now b2bg304823h32h2
```

## dataset commands
@@ -342,8 +367,9 @@ cat file.json | dat import -

### Options

- `key` - specify which field to use as the primary key
- `key`/`k` - specify which field to use as the primary key
- `no-key` - generate a random unique key
- `message`/`m` - a short description of this import

Example output:

@@ -438,3 +464,25 @@ Example output:
$ dat get uw60748112
{"key":"uw60748112","version":"5abd6625cd2e64a116628a9a306de2fbd73a05ea5905e26d5d4e58e077be2203","value":{"time":"2014-04-30T00:09:37.000Z","latitude":"46.7557","longitude":"-121.9855","place":"24km ESE of Eatonville, Washington","type":"earthquake"}}
```

### dat forks

List the current forks

```
dat forks
```

Example output:

```
$ dat forks
64843f272df9526fb04adb64fdf220330c9a29a8104c9ae4dead6b0aab5748e3 - Imported csv
163c6089c3477eecfa42420b4249f481b61c30b63071079e51cb052451862502 - Updated names
```

```
$ dat forks --json
{version: "64843f272df9526fb04adb64fdf220330c9a29a8104c9ae4dead6b0aab5748e3", message: "Imported csv"}
{version: "163c6089c3477eecfa42420b4249f481b61c30b63071079e51cb052451862502", message: "Updated names"}
```

bin/heads.js → bin/forks.js

@@ -1,13 +1,13 @@
var usage = require('../lib/usage.js')('heads.txt')
var usage = require('../lib/usage.js')('forks.txt')
var openDat = require('../lib/open-dat.js')
var abort = require('../lib/abort.js')

module.exports = {
  name: 'heads',
  command: handleHeads
  name: 'forks',
  command: handleForks
}

function handleHeads (args) {
function handleForks (args) {
  if (args.help) return usage()
  openDat(args, function ready (err, db) {
    if (err) abort(err)

bin/status.js

@@ -1,3 +1,5 @@
var prettyBytes = require('pretty-bytes')
var relativeDate = require('relative-date')
var abort = require('../lib/abort.js')
var openDat = require('../lib/open-dat.js')
var usage = require('../lib/usage.js')('checkout.txt')
@@ -13,14 +15,17 @@ function handleStatus (args) {
  openDat(args, function ready (err, db) {
    if (err) abort(err)

    db.open(function () {
      if (args.l === 'json') {
        var output = {
          'version': db.head
        }
        console.log(JSON.stringify(output))
    db.status(function (err, status) {
      if (args.log === 'json') {
        console.log(JSON.stringify(status))
      } else {
        console.error('Current version is', db.head)
        var output = ''
        output += 'Current version is ' + status.head
        if (!status.checkout) output += ' (latest)\n'
        else output += '\n'
        output += status.rows + ' keys, ' + status.files + ' files, ' + status.versions + ' versions, ' + prettyBytes(status.size) + ' total\n'
        output += 'Last updated ' + relativeDate(status.modified)
        console.error(output)
      }
    })
  })

cli.js

@@ -17,7 +17,7 @@ var config = {
    require('./bin/diff.js'),
    require('./bin/write.js'),
    require('./bin/cat.js'),
    require('./bin/heads.js'),
    require('./bin/forks.js'),
    require('./bin/merge.js')
  ],
  defaults: require('./bin/defaults.js'),

package.json

@@ -39,6 +39,7 @@
    "pump": "^1.0.0",
    "pumpify": "^1.3.3",
    "readable-stream": "^1.0.33",
    "relative-date": "^1.1.2",
    "sorted-diff-stream": "^1.0.0",
    "subcommand": "^2.0.1",
    "through2": "^0.6.3",

tests/checkout.js

@@ -31,8 +31,8 @@ test('dat1 heads', function (t) {
})

test('dat1 gets proper export', function (t) {
  var checkout = spawn(t, dat + ' checkout -d checkout-test-dataset ' + hashes[0], {cwd: dat1, end: false})
  checkout.stderr.match(new RegExp('Current version is now ' + hashes[0]))
  var checkout = spawn(t, dat + ' checkout -d checkout-test-dataset ' + hashes[1], {cwd: dat1, end: false})
  checkout.stderr.match(new RegExp('Current version is now ' + hashes[1]))
  checkout.stdout.empty()
  checkout.end(function () {
    var exp = spawn(t, dat + ' export -d checkout-test-dataset', {cwd: dat1})

tests/export.js

@@ -166,7 +166,7 @@ test('dat heads', function (t) {
})

test('dat export with checkout', function (t) {
  var st = spawn(t, dat + ' export --dataset=max --checkout=' + hashes[0], {cwd: dat2})
  var st = spawn(t, dat + ' export --dataset=max --checkout=' + hashes[1], {cwd: dat2})
  st.stderr.empty()
  st.stdout.match(function match (output) {
    try {
@@ -180,7 +180,7 @@ test('dat export with checkout', function (t) {
})

test('dat export with checkout hash 1', function (t) {
  var st = spawn(t, dat + ' export --dataset=max --checkout=' + hashes[1], {cwd: dat2})
  var st = spawn(t, dat + ' export --dataset=max --checkout=' + hashes[0], {cwd: dat2})
  st.stderr.empty()
  st.stdout.match(function match (output) {
    try {
@@ -194,7 +194,7 @@ test('dat export with checkout hash 1', function (t) {
})

test('dat export with checkout hash 1 abbr', function (t) {
  var st = spawn(t, dat + ' export -d max -c ' + hashes[1], {cwd: dat2})
  var st = spawn(t, dat + ' export -d max -c ' + hashes[0], {cwd: dat2})
  st.stderr.empty()
  st.stdout.match(function match (output) {
    try {

usage/forks.txt

@@ -0,0 +1,3 @@
dat forks

prints out all forks