dolt/{bats,go}: Improve output and README for git-dolt (#1682)

* dolt/{bats,go}: Improve output for git dolt update command

* dolt/go/cmd/git-dolt/README.md: Add install and update commands

* dolt/go/cmd/git-dolt/README.md: Add example of usage

bats/git-dolt.bats

@@ -106,7 +106,7 @@ teardown() {
 	run git dolt update test-repo $NEW_DOLT_HEAD_COMMIT
 
 	[ "$status" -eq 0 ]
-	[ "${lines[0]}" = "Updated pointer file test-repo.git-dolt to revision $NEW_DOLT_HEAD_COMMIT" ]
+	[ "${lines[0]}" = "Updated pointer file test-repo.git-dolt to revision $NEW_DOLT_HEAD_COMMIT. You should git commit this change." ]
 
 	run cat test-repo.git-dolt
 	[[ "${lines[0]}" =~ ^version\ [0-9]+\.[0-9]+\.[0-9]+$ ]] || false

go/cmd/git-dolt/README.md

@@ -17,8 +17,101 @@ remote http://dolthub.com/some-org/some-repo
 revision eidemcn2rsa5r1kpr5ds7mi0g5h8jt37
 ```
 
+## Example
+
+### Setup
+
+Make sure that `git-dolt` and `git-dolt-smudge` are in your PATH. Then do the steps below in a new directory somewhere:
+
+```
+$ git init
+Initialized empty Git repository in /Users/mjesuele/dolt/git-dolt-smudge-test/.git/
+
+$ git dolt install
+Installed git-dolt smudge filter.
+When git-dolt pointer files are checked out in this git repository, the corresponding Dolt repositories will be automatically cloned.
+
+$ git dolt link Liquidata/lunch-places
+
+Dolt repository successfully linked!
+
+* Dolt repository cloned to lunch-places at revision qi331vjgoavqpi5am334cji1gmhlkdv5
+* Pointer file created at lunch-places.git-dolt
+* lunch-places added to .gitignore
+
+You should git commit these results.
+
+$ git add .
+
+$ git commit -m set up git-dolt integration
+[master (root-commit) 82c762e] set up git-dolt integration
+ 3 files changed, 5 insertions(+)
+ create mode 100644 .gitattributes
+ create mode 100644 .gitignore
+ create mode 100644 lunch-places.git-dolt
+```
+
+### Testing the smudge filter
+
+```
+$ rm -rf lunch-places lunch-places.git-dolt
+
+$ git checkout -- lunch-places.git-dolt
+Found git-dolt pointer file. Cloning remote Liquidata/lunch-places to revision qi331vjgoavqpi5am334cji1gmhlkdv5 in directory lunch-places...done.
+
+$ cd lunch-places
+
+$ dolt log -n 3
+commit qi331vjgoavqpi5am334cji1gmhlkdv5
+Author: bheni <brian@liquidata.co>
+Date:   Thu Jun 06 17:22:24 -0700 2019
+
+	update tocaya rating
+
+commit eidemcn2rsa5r1kpr5ds7mi0g5h8jt37
+Merge: 137qgvrsve1u458briekqar5f7iiqq2j ngfah8jf5r9apr7bds87nua9uavnlc1d
+Author: Aaron Son <aaron@liquidata.co>
+Date:   Thu Apr 18 13:04:18 -0700 2019
+
+	Merge...
+
+commit 137qgvrsve1u458briekqar5f7iiqq2j
+Author: bheni <brian@liquidata.co>
+Date:   Thu Apr 04 15:43:00 -0700 2019
+
+	change rating
+```
+
 ## Commands
 
+### install
+
+```
+git dolt install
+```
+
+Initializes a git-dolt integration in the current git repository by:
+
+1. Adding a line in `.gitattributes` declaring the git-dolt smudge filter on `.git-dolt` files.
+2. Adding a line in `.git/config` telling git which executable(s) to use for the git-dolt filter.
+
+Once this is done, any time a `.git-dolt` file is checked out in the git repository, the Dolt
+repository that it points to will automatically be cloned to the specified revision.
+
+Note that this functionality requires that the `git-dolt-smudge` executable be present in your `PATH`.
+
+See [the chapter in Pro Git on Git Attributes](https://git-scm.com/book/en/v2/Customizing-Git-Git-Attributes)
+for more information about filters.
+
+_Example:_
+
+```
+$ git dolt install
+Installed git-dolt smudge filter. When git-dolt pointer files are checked out in this git repository, the corresponding Dolt repositories will be automatically cloned.
+
+You should git commit the changes to .gitattributes.
+```
+
 ### link
 
 ```
@@ -66,14 +159,21 @@ Currently, dolt lacks detached head support, meaning that you can't check out in
 
 Accordingly, the current behavior of `git dolt fetch` is to clone the remote repository and create/check out a new branch called `git-dolt-pinned` which points at the specified commit.
 
+### update
+
+```
+git dolt update <pointer-file> <revision>
+```
+
+Updates the given git-dolt pointer file to point to the specified revision.
+
+_Example:_
+
+```
+$ git dolt update im-interested ppbq8n1difju3u02jf8iqmctd1ovbj76
+Updated pointer file im-interested.git-dolt to revision ppbq8n1difju3u02jf8iqmctd1ovbj76. You should git commit this change.
+```
+
 ### Tests
 
 There are unit tests in Go and CLI tests using [BATS](https://github.com/sstephenson/bats).
-
-### Next steps:
-
-- Better error messaging (when underlying exec'd processes fail, we need to do more than just report their nonzero exit status)
-- Support updating the revision in the persistent pointer file
-- Use git's smudge filter to automatically fetch dolt repositories when checking out a git repository with git-dolt pointer files
-- Even more test coverage
-- ...and much more

go/cmd/git-dolt/commands/update.go

@@ -21,6 +21,6 @@ func Update(ptrFname string, revision string) error {
 	if err := config.Write(ptrFname, c.String()); err != nil {
 		return err
 	}
-	fmt.Printf("Updated pointer file %s to revision %s\n", ptrFname, revision)
+	fmt.Printf("Updated pointer file %s to revision %s. You should git commit this change.\n", ptrFname, revision)
 	return nil
 }