Extend worked example and make several refinements

* Verbosity control
* Automatically update working tree
* Identify orphan files in filter-clean and pass through so they don't
  show up as suprious diffs.

1 files changed, 87 insertions, 19 deletions

diff --git a/README.md b/README.md
index f5a9a07..8a4b806 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,19 @@
 # Installation and configuration
 Place `git-fat` in your `PATH`.
 
-To use `git-fat` edit `.gitattributes` to regard any desired extensions
-as fat files, e.g.
+Edit `.gitattributes` to regard any desired extensions as fat files.
 
+    $ cat >> .gitattributes
     *.png filter=fat -crlf
     *.jpg filter=fat -crlf
     *.gz  filter=fat -crlf
+    ^D
 
-then run `git fat init` to active the extension. Now add and commit as
-usual, all matched files will not go in `.git/objects`, but will appear
-complete in the working tree. To set a remote store for the fat objects,
-edit `.gitfat`
+Run `git fat init` to active the extension. Now add and commit as usual.
+Matched files will be transparently stored externally, but will appear
+complete in the working tree.
+
+Set a remote store for the fat objects by editing `.gitfat`.
 
     [rsync]
     remote = your.remote-host.org:/share/fat-store
@@ -23,13 +25,20 @@ remote ssh in a directory with shared access.
 
 # A worked example
 
-    $ export GIT_FAT_VERBOSE=1              # Show more verbose information about what is happening
+Before we start, let's turn on verbose reporting so we can see what's
+happening. Without this environment variable, all the output lines
+starting with `git-fat` will not be shown.
+
+    $ export GIT_FAT_VERBOSE=1
+
+First, we create a repository and configure it for use with `git-fat`.
+
     $ git init repo
     Initialized empty Git repository in /tmp/repo/.git/
     $ cd repo
     $ git fat init
     $ cat > .gitfat
-    [rsync] 
+    [rsync]
     remote = localhost:/tmp/fat-store
     $ mkdir -p /tmp/fat-store               # make sure the remote directory exists
     $ echo '*.gz filter=fat -crlf' > .gitattributes
@@ -39,6 +48,9 @@ remote ssh in a directory with shared access.
      2 files changed, 3 insertions(+)
      create mode 100644 .gitattributes
      create mode 100644 .gitfat
+
+Now we add a binary file whose name matches the pattern we set in `.gitattributes`.
+
     $ curl https://nodeload.github.com/jedbrown/git-fat/tar.gz/master -o master.tar.gz
       % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                      Dload  Upload   Total   Spent    Left  Speed
@@ -50,16 +62,34 @@ remote ssh in a directory with shared access.
     git-fat filter-clean: caching to /tmp/repo/.git/fat/objects/b3489819f81603b4c04e8ed134b80bace0810324
      1 file changed, 1 insertion(+)
      create mode 100644 master.tar.gz
-    $ du -s .git/objects .git/fat
+
+The patch itself is very simple and does not include the binary.
+
+    $ git show --pretty=oneline HEAD
+    918063043a6156172c2ad66478c6edd5c7df0217 Add master.tar.gz
+    diff --git a/master.tar.gz b/master.tar.gz
+    new file mode 100644
+    index 0000000..12f7d52
+    --- /dev/null
+    +++ b/master.tar.gz
+    @@ -0,0 +1 @@
+    +#$# git-fat 1f218834a137f7b185b498924e7a030008aee2ae
+
+## Pushing fat files
+Now let's push our fat files using the rsync configuration that we set up earlier.
+
     $ git fat push
     Pushing to localhost:/tmp/fat-store
-    building file list ... 
+    building file list ...
     1 file to consider
-    
+
     sent 61 bytes  received 12 bytes  48.67 bytes/sec
     total size is 6449  speedup is 88.34
 
-We could now push to a remote 
+We we might normally set a remote now and push the git repository.
+
+## Cloning and pulling
+Now let's look at what happens when we clone.
 
     $ cd ..
     $ git clone repo repo2
@@ -67,28 +97,66 @@ We could now push to a remote
     done.
     $ cd repo2
     $ git fat init                          # don't forget
+    $ ls -l                                 # file is just a placeholder
+    total 4
+    -rw-r--r--  1 jed  users  53 Nov 25 22:42 master.tar.gz
+    $ cat master.tar.gz                     # holds the SHA1 of the file
+    #$# git-fat 1f218834a137f7b185b498924e7a030008aee2ae
+
+We can always get a summary of what fat objects are missing in our local cache.
+
+    Orphan objects:
+    1f218834a137f7b185b498924e7a030008aee2ae
+
+Now get any objects referenced by our current `HEAD`. This command also
+accepts the `--all` option to pull full history, or a revspec to pull
+selected history.
+
     $ git fat pull
-    receiving file list ... 
+    receiving file list ...
     1 file to consider
     1f218834a137f7b185b498924e7a030008aee2ae
             6449 100%    6.15MB/s    0:00:00 (xfer#1, to-check=0/1)
     
     sent 30 bytes  received 6558 bytes  4392.00 bytes/sec
     total size is 6449  speedup is 0.98
-    $ cat master.tar.gz                     # we should checkout automatically
-    #$# git-fat 1f218834a137f7b185b498924e7a030008aee2ae
-    $ git checkout -f .
-    git-fat filter-clean: caching to /tmp/repo2/.git/fat/objects/b7939480ed4e54109f8f82d43e46a39e144ecad1
+    Restoring 1f218834a137f7b185b498924e7a030008aee2ae -> master.tar.gz
     git-fat filter-smudge: restoring from /tmp/repo2/.git/fat/objects/1f218834a137f7b185b498924e7a030008aee2ae
+
+Everything is in place
+
+    $ git status
+    git-fat filter-clean: caching to /tmp/repo2/.git/fat/objects/1f218834a137f7b185b498924e7a030008aee2ae
+    # On branch master
+    nothing to commit, working directory clean
     $ ls -l                                 # recovered the full file
     total 8
     -rw-r--r-- 1 jed users 6449 Nov 25 17:10 master.tar.gz
 
-# Important refinements
+## Summary
+* Set the "fat" file types in `.gitattributes`.
+* Use normal git commands to interact with the repository without
+  thinking about what files are fat and non-fat. The fat files will be
+  treated specially.
+* Synchronize fat files with `git fat push` and `git fat pull`.
+
+## Implementation notes
+The actual binary files are stored in `.git/fat/objects`, leaving `.git/objects` nice and small.
+
+    $ du -bs .git/objects
+    2212    .git/objects/
+    $ ls -l .git/fat/objects                # This is where the file actually goes, but that's not important
+    total 8
+    -rw------- 1 jed users 6449 Nov 25 17:01 1f218834a137f7b185b498924e7a030008aee2ae
+
+# Some refinements
+* Allow pulling and pushing only select files
+* Relate orphan objects to file system
 * Put some more useful message in smudged (working tree) version of missing files.
-* Make 
+* More friendly configuration for multiple fat remotes
 * Make commands safer in presence of a dirty tree.
 * Private setting of a different remote.
 * Gracefully handle unmanaged files when the filter is called (either
   legacy files or files matching the pattern that should some reason not
   be treated as fat).
+* Don't append the [filter "fat"] section to .git/config if it doesn't already exist.