diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/devblog/day_410__better_JSON_for_metadata.mdwn | 33 | ||||
| -rw-r--r-- | doc/git-annex-metadata.mdwn | 10 | ||||
| -rw-r--r-- | doc/todo/metadata_--batch/comment_4_c72eb16b630b200265e125ebaf7d0d36._comment | 36 |
3 files changed, 79 insertions, 0 deletions
diff --git a/doc/devblog/day_410__better_JSON_for_metadata.mdwn b/doc/devblog/day_410__better_JSON_for_metadata.mdwn new file mode 100644 index 000000000..a1270e702 --- /dev/null +++ b/doc/devblog/day_410__better_JSON_for_metadata.mdwn @@ -0,0 +1,33 @@ +I've had to change the output of `git annex metadata --json`. +The old output looked like this: + + {"command":"metadata","file":"foo","key":"...","author":["bar"],...,"note":"...","success":true} + +That was not good, because it didn't separate the metadata fields +from the rest of the JSON object. What if a metadata field is named +"note" or "success"? It would collide with the other "note" and "success" +in the JSON. + +So, changed this to a new format, which moves the metadata fields into +a "fields" object: + + {"command":"metadata","file":"foo","key":"...","fields":{"author":["bar"],...},"note":"...","success":true} + +I don't like breaking backwards compatability of JSON output, but in this +case I could see no real alternative. I don't know if anyone +is using `metadata --batch` anyway. If you are and this will cause a +problem, get in touch. + +---- + +While making that change, I also improved the JSON outputlayer, so it can +use Aeson. I didn't switch exclusively to using Aeson, because git-annex +commands with JSON output often output it incrementally as they go (which +Aeson can't really do), and are anyway not often doing the kind of +serialization of data type that Aeson excells at. + +This let me use Aeson to generate the "fields" object for `metadata +--json`. And it was also easy enough to use Aeson to parse the output of +that command (and some simplified forms of it). + +So, I've laid the groundwork for `git annex metadata --batch` today. diff --git a/doc/git-annex-metadata.mdwn b/doc/git-annex-metadata.mdwn index fe344ff5e..b4e790080 100644 --- a/doc/git-annex-metadata.mdwn +++ b/doc/git-annex-metadata.mdwn @@ -71,6 +71,16 @@ When run without any -s or -t parameters, displays the current metadata. Enable JSON output. This is intended to be parsed by programs that use git-annex. Each line of output is a JSON object. + The format of the JSON objects changed in git-annex version 6.20160726. + + Example of the new format: + + {"command":"metadata","file":"foo","key":"...","fields":{"author":["bar"],...},"note":"...","success":true} + + Example of the old format, which lacks the inner fields object: + + {"command":"metadata","file":"foo","key":"...","author":["bar"],...,"note":"...","success":true} + * `--all` Specify instead of a file to get/set metadata on all known keys. diff --git a/doc/todo/metadata_--batch/comment_4_c72eb16b630b200265e125ebaf7d0d36._comment b/doc/todo/metadata_--batch/comment_4_c72eb16b630b200265e125ebaf7d0d36._comment new file mode 100644 index 000000000..4cd0f2d34 --- /dev/null +++ b/doc/todo/metadata_--batch/comment_4_c72eb16b630b200265e125ebaf7d0d36._comment @@ -0,0 +1,36 @@ +[[!comment format=mdwn + username="joey" + subject="""comment 4""" + date="2016-07-25T17:39:37Z" + content=""" +--batch mode should be usable to get current metadata, set new +metadata, and remove existing metadata. The non-batch metadata command has +different syntaxes for all of these, but it would be good to have a single +interface that handles all three in batch mode. + +It could read a line containing the file or key, with any metadata +fields that should be changed: + + {"file":"foo"} + {"file":"foo","author":["bar"]} + {"key":"SHA...","author":[]} + +And reply with *all* the metadata, in nearly the same format: + + {"file":"foo","key":"SHA...","author":["bar"],lastchanged:["date"],"success":true} + +And that reply could in turn be edited and fed back in to change the +metadata. + +---- + +There's a DRY problem here because there's the current JSON generator code, +and I'd have to add an Aeson parser to parse the JSON input. But, Aeson +parsers also automatically have a matching generator, which is guaranteed +to generate code that the parser can parse. + +So, it would be nice to use the Aeson JSON generator, instead of the +current one, but that can only be done if the JSON is formatted the same, +or close enough that nothing currently consuming `metadata --json` will +break. +"""]] |