add metadata command to get/set metadata

Adds metadata log, and command.

Note that unsetting field values seems to currently be broken.
And in general this has had all of 2 minutes worth of testing.

This commit was sponsored by Julien Lefrique.

3 files changed, 38 insertions, 14 deletions

diff --git a/doc/design/metadata.mdwn b/doc/design/metadata.mdwn
index 40c085cdc..3e2d4bf08 100644
--- a/doc/design/metadata.mdwn
+++ b/doc/design/metadata.mdwn
@@ -145,20 +145,6 @@ a tag was removed:
 	1287290991.152124s tag +baz
 	1291237510.141453s tag -bar
 
-The end result is that tags foo and baz are set. This can be simplified:
-
-	1291237510.141453s tag +foo +baz -bar
-
-Note the reuse of the most recent timestamp in the simplified version,
-rather than putting in the timestamp when the simplification was done.
-This ensures that is some other repo is making changes, they won't get
-trampled over. For example:
-
-	1291237510.141453s tag +foo +baz -bar
-	1291239999.000000s tag +bar -foo
-
-Now tags bar and baz are set.
-
 # efficient metadata lookup
 
 Looking up metadata for filtering so far requires traversing all keys in
diff --git a/doc/git-annex.mdwn b/doc/git-annex.mdwn
index 4e672f608..17d78c555 100644
--- a/doc/git-annex.mdwn
+++ b/doc/git-annex.mdwn
@@ -695,6 +695,23 @@ subdirectories).
 
 # UTILITY COMMANDS
 
+* `metadata file [field=value field+=value field-=value ...]`
+
+  Each file can have any number of metadata fields attached to it,
+  which each in turn have any number of values. This sets metadata
+  for a file, or if run without any values, shows its current metadata.
+
+  To set a field's value, removing any old value(s), use field=value.
+
+  To add an additional value, use field+=value.
+
+  To remove a value, use field-=value.
+
+  For example, to set some tags on a file:
+
+        	git annex metadata annexscreencast.ogv tag+=video tag+=screencast
+
+
 * `migrate [path ...]`
 
   Changes the specified annexed files to use the default key-value backend
diff --git a/doc/internals.mdwn b/doc/internals.mdwn
index 1cf0cf505..970e88ba0 100644
--- a/doc/internals.mdwn
+++ b/doc/internals.mdwn
@@ -146,6 +146,27 @@ Example:
 	1287290776.765152s e605dca6-446a-11e0-8b2a-002170d25c55 blah blah
 	1287290767.478634s 26339d22-446b-11e0-9101-002170d25c55 foo=bar
 
+## `aaa/bbb/*.log.met`
+
+These log files are used to store arbitrary [[design/metadata]] about keys.
+Each key can have any number of metadata fields. Each field has a set of
+values.
+
+Lines are timestamped, and record when values are added (`field +value`),
+but also when values are removed (`field -value`). Removed values
+are retained in the log so that when merging an old line that sets a value
+that was later unset, the value is not accidentially added back.
+
+For example:
+
+	1287290776.765152s tag +foo +bar author +joey
+	1291237510.141453s tag -bar +baz
+
+The value can be completely arbitrary data, although it's typically
+reasonably short. If the value contains any whitespace
+(including \r or \r), it will be base64 encoded. Base64 encoded values
+are indicated by prefixing them with "!" 
+
 ## `schedule.log`
 
 Used to record scheduled events, such as periodic fscks.