Merge branch 'view'

2 files changed, 43 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..3b9a227be 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -313,6 +313,35 @@ 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.
+
+* `vpop`
+
+  Switches from the currently active view back to the previous view.
+  Or, from the first view back to original branch.
+
+* `vadd [field=value ...] [tag ...]`
+
+  Refines the currently checked out view branch, adding additional fields
+  or tags.
+
+* `vcycle`
+
+  When a view involves nested subdirectories, this cycles the order.
+  For example, when the view has date/author/tag, vcycle will switch
+  it to author/tag/date.
+
 # REPOSITORY SETUP COMMANDS
 
 * `init [description]`