add git annex view command

(And a vpop command, which is still a bit buggy.)

Still need to do vadd and vrm, though this also adds their documentation.

Currently not very happy with the view log data serialization. I had to
lose the TDFA regexps temporarily, so I can have Read/Show instances of
View. I expect the view log format will change in some incompatable way
later, probably adding last known refs for the parent branch to View
or something like that.

Anyway, it basically works, although it's a bit slow looking up the
metadata. The actual git branch construction is about as fast as it can be
using the current git plumbing.

This commit was sponsored by Peter Hogg.

2 files changed, 41 insertions, 14 deletions

diff --git a/doc/design/metadata.mdwn b/doc/design/metadata.mdwn
index 4edfa6d72..0e8727415 100644
--- a/doc/design/metadata.mdwn
+++ b/doc/design/metadata.mdwn
@@ -36,37 +36,37 @@ sql queries if we want to go that far.)
 
 # filtered branches
 
-`git annex filter year=2014 talk` should create a new branch
-filtered/year=2014/talk containing only files tagged with that, and
+`git annex view year=2014 talk` should create a new branch
+view/year=2014/talk containing only files tagged with that, and
 have git check it out. In this example, all files appear in top level
 directory of repo; no subdirs.
 
-`git annex fadd haskell` switches to branch
-filtered/year=2014/talk/haskell with only the haskell talks.
+`git annex vadd haskell` switches to branch
+view/year=2014/talk/haskell with only the haskell talks.
 
-`git annex fadd year=2013 year=2012` switches to branch
-filtered/year=2012,2013,2014/talk/haskell. This has subdirectories 2012,
+`git annex vadd year=2013 year=2012` switches to branch
+view/year=2012,2013,2014/talk/haskell. This has subdirectories 2012,
 2013 and 2014 with the matching talks.
 
 Patterns can be used in both the values of fields, and in matching tags.
 So, `year=20*` could be used to match years, and `foo/*` matches any
 tag in the foo namespace. Or even `*` to match *all* tags.
 
-`git annex frm haskell` switches to
-filtered/year=2012,2013,2014/talk, which has all available talks in it.
+`git annex vrm haskell` switches to
+view/year=2012,2013,2014/talk, which has all available talks in it.
 
-`git annex fadd conference=fosdem conference=icfp` switches to branch
-filtered/year=2012,2013,2014/talk/conference=fosdem,icfp. Now there
+`git annex vadd conference=fosdem conference=icfp` switches to branch
+view/year=2012,2013,2014/talk/conference=fosdem,icfp. Now there
 are nested subdirectories. They follow the format of the branch,
 so 2013/icfp, 2014/fosdem, etc.
 
-`git annex filter tag=haskell,debian` yields a branch with haskell
+`git annex view tag=haskell,debian` yields a branch with haskell
 and debian subdirectories.
 
-To see all tags, `git annex filter tag=*` !
+To see all tags, as subdirectories, `git annex view tag=*` !
 
-Files not matching the filter can be included, by using 
-`git annex filter --unmatched=other`. That puts all such files into
+Files not matching the view can be included, by using 
+`git annex view --unmatched=other`. That puts all such files into
 the subdirectory other.
 
 Note that old filter branches can be deleted when switching to a new one.
diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 1b7271092..84cb55a43 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -313,6 +313,33 @@ subdirectories).
   from a remote computer.
   Note that this does not yet use HTTPS for security, so use with caution!
 
+* `view [field=value ...] [tag ...]`
+
+  Uses metadata to build a view branch of the files in the current branch,
+  and checks out the view branch. Only files in the current branch whose
+  metadata matches all the specified field values and tags will be
+  shown in the view.
+  
+  Multiple values for a metadata field can be specified, either by using
+  a glob (field="\*") or by listing each wanted value. 
+  
+  When multiple field values match, the view branch will have a
+  subdirectory for each value.
+
+* `vadd [field=value ...] [tag ...]`
+
+  Can be used when already in a view to add additional fields or tags
+  to the view.
+
+* `vrm [field=value ...] [tag ...]`
+
+  Can be used when already in a view to remove fields or tags from the
+  view.
+
+* `vpop`
+
+  Switches from the currently active view back to the previous view.
+
 # REPOSITORY SETUP COMMANDS
 
 * `init [description]`