Added metadata --batch option, which allows getting, setting, deleting, and modifying metadata for multiple files/keys.

1 files changed, 51 insertions, 12 deletions

diff --git a/doc/git-annex-metadata.mdwn b/doc/git-annex-metadata.mdwn
index b4e790080..fde4443dc 100644
--- a/doc/git-annex-metadata.mdwn
+++ b/doc/git-annex-metadata.mdwn
@@ -17,6 +17,11 @@ metadata.
 
 When run without any -s or -t parameters, displays the current metadata.
 
+Each metadata field has its own "field-lastchanged" metadata, which
+contains the date the field was last changed. Unlike other metadata,
+this cannot be directly modified by this command. It is updated
+automatically.
+
 # OPTIONS
 
 * `-g field` / `--get field`
@@ -66,10 +71,27 @@ When run without any -s or -t parameters, displays the current metadata.
   The [[git-annex-matching-options]](1)
   can be used to specify files to act on.
 
+* `--all`
+
+  Specify instead of a file to get/set metadata on all known keys.
+
+* `--branch=ref`
+
+  Specify instead of a file to get/set metadata on all files in the
+  specified branch or treeish.
+
+* `--unused`
+
+  Specify instead of a file to get/set metadata on
+  files found by last run of git-annex unused.
+
+* `--key=keyname`
+
+  Specify instead of a file to get/set metadata of the specified key.
+
 * `--json`
 
-  Enable JSON output. This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
+  Enable JSON output (and input). Each line is a JSON object.
 
   The format of the JSON objects changed in git-annex version 6.20160726.
 
@@ -81,23 +103,40 @@ When run without any -s or -t parameters, displays the current metadata.
 
 	{"command":"metadata","file":"foo","key":"...","author":["bar"],...,"note":"...","success":true}
 
-* `--all`
+* `--batch`
 
-  Specify instead of a file to get/set metadata on all known keys.
+  Enables batch mode, which can be used to both get, store, and unset
+  metadata for multiple files or keys.
 
-* `--branch=ref`
+  Batch currently only supports JSON input. So, you must
+  enable `--json` along with `--batch`.
 
-  Specify instead of a file to get/set metadata on all files in the
-  specified branch or treeish.
+  In batch mode, git-annex reads lines from stdin, which contain
+  JSON objects. It replies to each input with an output JSON object.
 
-* `--unused`
+  The format of the JSON sent to git-annex can be the same as the JSON that
+  it outputs. Or, a simplified version. Only the "file" (or "key") field
+  is actually necessary.
 
-  Specify instead of a file to get/set metadata on
-  files found by last run of git-annex unused.
+  For example, to get the current metadata of file foo:
 
-* `--key=keyname`
+	{"file":"foo"}
 
-  Specify instead of a file to get/set metadata of the specified key.
+  To get the current metadata of the key k:
+	
+	{"key":"k"}
+
+  Any metadata fields included in the JSON object will be stored,
+  replacing whatever values the fields had before.
+  To unset a field, include it with an empty list of values.
+
+  To change the author of file foo to bar:
+
+	{"file":"foo","fields":{"author":["bar"]}}
+
+  To remove the author of file foo:
+
+	{"file":"foo","fields":{"author":[]}}
 
 # EXAMPLES