migrate, undo: Support --json and --json-error-messages

Sponsored-By: the NIH-funded NICEMAN (ReproNim TR&D3) project

CHANGELOG

@@ -38,7 +38,7 @@ git-annex (10.20230408) UNRELEASED; urgency=medium
   * initremote: Avoid creating a remote that is not encrypted when gpg is
     broken.
   * Support --json and --json-error-messages in more commands
-    (fix, log, rekey, rmurl, setpresentkey, unannex)
+    (fix, log, migrate, rekey, rmurl, setpresentkey, unannex, undo)
   * log: When --raw-date is used, display only seconds from the epoch, as
     documented, omitting a trailing "s" that was included in the output
     before.

Command/Migrate.hs

@@ -20,7 +20,7 @@ import Logs.Web
 import Utility.Metered
 
 cmd :: Command
-cmd = withAnnexOptions [backendOption, annexedMatchingOptions] $
+cmd = withAnnexOptions [backendOption, annexedMatchingOptions, jsonOptions] $
 	command "migrate" SectionUtility 
 		"switch data to different backend"
 		paramPaths (seek <$$> optParser)

Command/Undo.hs

@@ -22,7 +22,7 @@ import qualified Command.Sync
 import qualified Utility.RawFilePath as R
 
 cmd :: Command
-cmd = notBareRepo $
+cmd = notBareRepo $ withAnnexOptions [jsonOptions] $
 	command "undo" SectionCommon 
 		"undo last change to a file or directory"
 		paramPaths (withParams seek)

doc/git-annex-migrate.mdwn

@@ -51,6 +51,16 @@ it's best to run migrate in all of them.
 
   	git-annex migrate --remove-size --backend=URL somefile
 
+* `--json`
+
+  Enable JSON output. This is intended to be parsed by programs that use
+  git-annex. Each line of output is a JSON object.
+
+* `--json-error-messages`
+
+  Messages that would normally be output to standard error are included in
+  the JSON instead.
+
 # SEE ALSO
 
 [[git-annex]](1)

doc/git-annex-undo.mdwn

@@ -24,7 +24,17 @@ operates on the file tree committed to git.
 
 # OPTIONS
 
-* The [[git-annex-common-options]](1) can be used.
+* `--json`
+
+  Enable JSON output. This is intended to be parsed by programs that use
+  git-annex. Each line of output is a JSON object.
+
+* `--json-error-messages`
+
+  Messages that would normally be output to standard error are included in
+  the JSON instead.
+
+* The [[git-annex-common-options]](1) can also be used.
 
 # SEE ALSO
 

doc/git-annex-whereused.mdwn

@@ -40,16 +40,6 @@ key. The `--historical` option makes it also find past versions of files.
   It stops after finding one use of the key, and outputs a git rev that
   refers to where it was used, eg "HEAD@{40}:somefile"
 
-* `--json`
-
-  Enable JSON output. This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
-
-* `--json-error-messages`
-
-  Messages that would normally be output to standard error are included in
-  the JSON instead.
-
 # SEE ALSO
 
 [[git-annex]](1)

doc/todo/--json_for_unannex__and_ideally_any_other_command_.mdwn

@@ -1,4 +1,14 @@
-While looking for various spots where `core.quotepath=true` is now treated by git-annex ([ref](https://github.com/datalad/datalad/pull/7372#issuecomment-1533507701)) I found that `unannex` doesn't have `--json` and we do some really ad-hoc splitting which fails with spaces and we never actually tested enough.  With all the `quotepath` and other fun, we really should get machine-readable, thus `--json`, output for all annex commands IMHO. E.g. `unannex` has recently come up within treatment of BIDS datasets, and so far we were lucky that BIDS filenames do not allow for spaces in the filenames, but there is always `derivatives/` and `sourcedata/` which are not formalized and could have all kinds of odd filenames.
+While looking for various spots where `core.quotepath=true` is now treated
+by git-annex
+([ref](https://github.com/datalad/datalad/pull/7372#issuecomment-1533507701))
+I found that `unannex` doesn't have `--json` and we do some really ad-hoc
+splitting which fails with spaces and we never actually tested enough.
+With all the `quotepath` and other fun, we really should get
+machine-readable, thus `--json`, output for all annex commands IMHO. E.g.
+`unannex` has recently come up within treatment of BIDS datasets, and so
+far we were lucky that BIDS filenames do not allow for spaces in the
+filenames, but there is always `derivatives/` and `sourcedata/` which are
+not formalized and could have all kinds of odd filenames.
 
 [[!meta author=yoh]]
 [[!tag projects/repronim]]
@@ -11,51 +21,38 @@ These commands have been updated to support --json:
 * git-annex-fix
 * git-annex-setpresentkey
 * git-annex-rekey
+* git-annex-undo
+* git-annex-migrate
 
 Provisional list of commands that don't support --json and maybe should:
 
 (Feel free to reorder things to the top)
 
-* git-annex-whereused
 * git-annex-addunused
 * git-annex-adjust
-* git-annex-backends
-* git-annex-config
 * git-annex-configremote
 * git-annex-dead
 * git-annex-describe
 * git-annex-dropunused
 * git-annex-edit
-* git-annex-enable-tor
 * git-annex-enableremote
 * git-annex-expire
-* git-annex-filter-branch
 * git-annex-forget
 * git-annex-group
-* git-annex-groupwanted
 * git-annex-importfeed
 * git-annex-init
 * git-annex-initremote
 * git-annex-inprogress
 * git-annex-merge
-* git-annex-migrate
 * git-annex-mincopies
-* git-annex-multicast
 * git-annex-numcopies
-* git-annex-preferred-content
 * git-annex-reinit
 * git-annex-reinject
-* git-annex-remotedaemon
 * git-annex-renameremote
-* git-annex-repair
-* git-annex-required
-* git-annex-schedule
 * git-annex-semitrust
 * git-annex-sync
 * git-annex-trust
-* git-annex-undo
 * git-annex-ungroup
-* git-annex-uninit
 * git-annex-untrust
 * git-annex-unused
 * git-annex-upgrade
@@ -63,10 +60,14 @@ Provisional list of commands that don't support --json and maybe should:
 * git-annex-vcycle
 * git-annex-version
 * git-annex-vfilter
-* git-annex-vicfg
 * git-annex-view
 * git-annex-vpop
-* git-annex-wanted
+
+These commands could support json, but I punted:
+
+* git-annex-uninit (hard to support --json-error-messages because it does
+  pre-check and post-unannex things that are not usual actions and so would
+  not show as json objects without more work)
 
 These commands have been reviewed and should not support json:
 
@@ -100,3 +101,16 @@ These commands have been reviewed and should not support json:
 * git-annex-diffdriver (run by git)
 * git-annex-restage (no output)
 * git-annex-benchmark (no useful output, and output generated by criterion)
+* git-annex-config (only useful output is when it outputs the current value
+  of a config setting, which is already machine parseable)
+* git-annex-required, git-annex-wanted, git-annex-groupwanted (like git-annex-config)
+* git-annex-schedule (like git-annex-config)
+* git-annex-filter-branch (output is already machine parseable)
+* git-annex-remotedaemon (plumbing, speaks its own protocol)
+* git-annex-repair (seems unlikely to be useful to integrate with
+  something?)
+* git-annex-vicfg (interactive)
+* git-annex-enable-tor (prompts for password, more or less interactive so
+  seems unlikely to be useful to jsonize)
+* git-annex-multicast (runs uftp and displays its output)
+* git-annex-whereused (output is already machine parseable)