add --json-error-messages (not yet implemented)

Added --json-error-messages option, which includes error messages in the
json output, rather than outputting them to stderr.

The actual rediretion of errors is not implemented yet, this is only
the docs and option plumbing.

This commit was supported by the NSF-funded DataLad project.

CHANGELOG

@@ -19,6 +19,8 @@ git-annex (6.20180113) UNRELEASED; urgency=medium
     compile.
   * Fix behavior of --json-progress followed by --json, in which
     the latter option disabled the former.
+  * Added --json-error-messages option, which includes error messages
+    in the json output, rather than outputting them to stderr.
 
  -- Joey Hess <id@joeyh.name>  Wed, 24 Jan 2018 20:42:55 -0400
 

CmdLine/GitAnnex/Options.hs

@@ -191,7 +191,7 @@ annexedMatchingOptions = concat
 	[ nonWorkTreeMatchingOptions'
 	, fileMatchingOptions'
 	, combiningOptions
-	, [timeLimitOption]
+	, timeLimitOption
 	]
 
 -- Matching options that don't need to examine work tree files.
@@ -294,37 +294,51 @@ combiningOptions =
 	longopt o h = globalFlag (Limit.addToken o) ( long o <> help h <> hidden )
 	shortopt o h = globalFlag (Limit.addToken [o]) ( short o <> help h <> hidden )
 
-jsonOption :: GlobalOption
+jsonOptions :: [GlobalOption]
-jsonOption = globalFlag (Annex.setOutput (JSONOutput jsonoptions))
+jsonOptions = 
-	( long "json" <> short 'j'
+	[ globalFlag (Annex.setOutput (JSONOutput stdjsonoptions))
-	<> help "enable JSON output"
+		( long "json" <> short 'j'
-	<> hidden
+		<> help "enable JSON output"
-	)
+		<> hidden
+		)
+	, globalFlag (Annex.setOutput (JSONOutput jsonerrormessagesoptions))
+		( long "json-error-messages"
+		<> help "include error messages in JSON"
+		<> hidden
+		)
+	]
   where
-	jsonoptions = JSONOptions
+	stdjsonoptions = JSONOptions
 		{ jsonProgress = False
+		, jsonErrorMessages = False
 		}
+	jsonerrormessagesoptions = stdjsonoptions { jsonErrorMessages = True }
 
-jsonProgressOption :: GlobalOption
+jsonProgressOption :: [GlobalOption]
-jsonProgressOption = globalFlag (Annex.setOutput (JSONOutput jsonoptions))
+jsonProgressOption = 
-	( long "json-progress"
+	[ globalFlag (Annex.setOutput (JSONOutput jsonoptions))
-	<> help "include progress in JSON output"
+		( long "json-progress"
-	<> hidden
+		<> help "include progress in JSON output"
-	)
+		<> hidden
+		)
+	]
   where
 	jsonoptions = JSONOptions
 		{ jsonProgress = True
+		, jsonErrorMessages = False
 		}
 
 -- Note that a command that adds this option should wrap its seek
 -- action in `allowConcurrentOutput`.
-jobsOption :: GlobalOption
+jobsOption :: [GlobalOption]
-jobsOption = globalSetter set $ 
+jobsOption = 
-	option auto
+	[ globalSetter set $ 
-		( long "jobs" <> short 'J' <> metavar paramNumber
+		option auto
-		<> help "enable concurrent jobs"
+			( long "jobs" <> short 'J' <> metavar paramNumber
-		<> hidden
+			<> help "enable concurrent jobs"
-		)
+			<> hidden
+			)
+	]
   where
 	set n = do
 		Annex.changeState $ \s -> s { Annex.concurrency = Concurrent n }
@@ -332,12 +346,14 @@ jobsOption = globalSetter set $
 		when (n > c) $
 			liftIO $ setNumCapabilities n
 
-timeLimitOption :: GlobalOption
+timeLimitOption :: [GlobalOption]
-timeLimitOption = globalSetter Limit.addTimeLimit $ strOption
+timeLimitOption = 
-	( long "time-limit" <> short 'T' <> metavar paramTime
+	[ globalSetter Limit.addTimeLimit $ strOption
-	<> help "stop after the specified amount of time"
+		( long "time-limit" <> short 'T' <> metavar paramTime
-	<> hidden
+		<> help "stop after the specified amount of time"
-	)
+		<> hidden
+		)
+	]
 
 data DaemonOptions = DaemonOptions
 	{ foregroundDaemonOption :: Bool

Command.hs

@@ -79,9 +79,9 @@ allowMessages = do
 noRepo :: (String -> Parser (IO ())) -> Command -> Command
 noRepo a c = c { cmdnorepo = Just (a (cmdparamdesc c)) }
 
-{- Adds global options to a command's. -}
+{- Adds global options to a command. -}
-withGlobalOptions :: [GlobalOption] -> Command -> Command
+withGlobalOptions :: [[GlobalOption]] -> Command -> Command
-withGlobalOptions os c = c { cmdglobaloptions = cmdglobaloptions c ++ os }
+withGlobalOptions os c = c { cmdglobaloptions = cmdglobaloptions c ++ concat os }
 
 {- For start and perform stages to indicate what step to run next. -}
 next :: a -> Annex (Maybe a)

Command/Add.hs

@@ -22,9 +22,10 @@ import Annex.Version
 import Git.FilePath
 
 cmd :: Command
-cmd = notBareRepo $ withGlobalOptions (jobsOption : jsonOption : fileMatchingOptions) $
+cmd = notBareRepo $ 
-	command "add" SectionCommon "add files to annex"
+	withGlobalOptions [jobsOption, jsonOptions, fileMatchingOptions] $
-		paramPaths (seek <$$> optParser)
+		command "add" SectionCommon "add files to annex"
+			paramPaths (seek <$$> optParser)
 
 data AddOptions = AddOptions
 	{ addThese :: CmdParams

Command/AddUrl.hs

@@ -34,7 +34,7 @@ import Utility.Path.Max
 import qualified Annex.Transfer as Transfer
 
 cmd :: Command
-cmd = notBareRepo $ withGlobalOptions [jobsOption, jsonOption, jsonProgressOption] $
+cmd = notBareRepo $ withGlobalOptions [jobsOption, jsonOptions, jsonProgressOption] $
 	command "addurl" SectionCommon "add urls to annex"
 		(paramRepeating paramUrl) (seek <$$> optParser)
 

Command/Copy.hs

@@ -14,7 +14,7 @@ import Annex.Wanted
 import Annex.NumCopies
 
 cmd :: Command
-cmd = withGlobalOptions (jobsOption : jsonOption : jsonProgressOption : annexedMatchingOptions) $
+cmd = withGlobalOptions [jobsOption, jsonOptions, jsonProgressOption, annexedMatchingOptions] $
 	command "copy" SectionCommon
 		"copy content of files to/from another repository"
 		paramPaths (seek <--< optParser)

Command/Drop.hs

@@ -23,7 +23,7 @@ import System.Log.Logger (debugM)
 import qualified Data.Set as S
 
 cmd :: Command
-cmd = withGlobalOptions (jobsOption : jsonOption : annexedMatchingOptions) $
+cmd = withGlobalOptions [jobsOption, jsonOptions, annexedMatchingOptions] $
 	command "drop" SectionCommon
 		"remove content of files from repository"
 		paramPaths (seek <$$> optParser)

Command/DropKey.hs

@@ -13,7 +13,7 @@ import Logs.Location
 import Annex.Content
 
 cmd :: Command
-cmd = noCommit $ withGlobalOptions [jsonOption] $
+cmd = noCommit $ withGlobalOptions [jsonOptions] $
 	command "dropkey" SectionPlumbing
 		"drops annexed content for specified keys"
 		(paramRepeating paramKey)

Command/ExamineKey.hs

@@ -13,7 +13,7 @@ import Command.Find (parseFormatOption, showFormatted, keyVars)
 
 cmd :: Command
 cmd = noCommit $ noMessages $ dontCheck repoExists $ 
-	withGlobalOptions [jsonOption] $
+	withGlobalOptions [jsonOptions] $
 		command "examinekey" SectionPlumbing 
 			"prints information from a key"
 			(paramRepeating paramKey)

Command/Find.hs

@@ -18,12 +18,12 @@ import qualified Utility.Format
 import Utility.DataUnits
 
 cmd :: Command
-cmd = withGlobalOptions annexedMatchingOptions $ mkCommand $
+cmd = withGlobalOptions [annexedMatchingOptions] $ mkCommand $
 	command "find" SectionQuery "lists available files"
 		paramPaths (seek <$$> optParser)
 
 mkCommand :: Command -> Command
-mkCommand = noCommit . noMessages . withGlobalOptions [jsonOption]
+mkCommand = noCommit . noMessages . withGlobalOptions [jsonOptions]
 
 data FindOptions = FindOptions
 	{ findThese :: CmdParams

Command/FindRef.hs

@@ -12,7 +12,7 @@ import qualified Command.Find as Find
 import qualified Git
 
 cmd :: Command
-cmd = withGlobalOptions nonWorkTreeMatchingOptions $ Find.mkCommand $ 
+cmd = withGlobalOptions [nonWorkTreeMatchingOptions] $ Find.mkCommand $ 
 	command "findref" SectionPlumbing
 		"lists files in a git ref"
 		paramRef (seek <$$> Find.optParser)

Command/Fix.hs

@@ -23,7 +23,7 @@ import Utility.Touch
 #endif
 
 cmd :: Command
-cmd = notDirect $ noCommit $ withGlobalOptions annexedMatchingOptions $
+cmd = notDirect $ noCommit $ withGlobalOptions [annexedMatchingOptions] $
 	command "fix" SectionMaintenance
 		"fix up links to annexed content"
 		paramPaths (withParams seek)

Command/Fsck.hs

@@ -45,7 +45,7 @@ import qualified Data.Set as S
 import qualified Data.Map as M
 
 cmd :: Command
-cmd = withGlobalOptions (jobsOption : jsonOption : annexedMatchingOptions) $
+cmd = withGlobalOptions [jobsOption, jsonOptions, annexedMatchingOptions] $
 	command "fsck" SectionMaintenance
 		"find and fix problems"
 		paramPaths (seek <$$> optParser)

Command/Get.hs

@@ -16,7 +16,7 @@ import Annex.Wanted
 import qualified Command.Move
 
 cmd :: Command
-cmd = withGlobalOptions (jobsOption : jsonOption : jsonProgressOption : annexedMatchingOptions) $ 
+cmd = withGlobalOptions [jobsOption, jsonOptions, jsonProgressOption, annexedMatchingOptions] $ 
 	command "get" SectionCommon 
 		"make content of annexed files available"
 		paramPaths (seek <$$> optParser)

Command/Import.hs

@@ -24,10 +24,11 @@ import Utility.InodeCache
 import Logs.Location
 
 cmd :: Command
-cmd = withGlobalOptions (jobsOption : jsonOption : fileMatchingOptions) $ notBareRepo $
+cmd = notBareRepo $
-	command "import" SectionCommon 
+	withGlobalOptions [jobsOption, jsonOptions, fileMatchingOptions] $
-		"move and add files from outside git working copy"
+		command "import" SectionCommon 
-		paramPaths (seek <$$> optParser)
+			"move and add files from outside git working copy"
+			paramPaths (seek <$$> optParser)
 
 data DuplicateMode = Default | Duplicate | DeDuplicate | CleanDuplicates | SkipDuplicates | ReinjectDuplicates
 	deriving (Eq)

Command/Info.hs

@@ -84,7 +84,7 @@ emptyStatInfo = StatInfo Nothing Nothing M.empty Nothing
 type StatState = StateT StatInfo Annex
 
 cmd :: Command
-cmd = noCommit $ withGlobalOptions (jsonOption : annexedMatchingOptions) $
+cmd = noCommit $ withGlobalOptions [jsonOptions, annexedMatchingOptions] $
 	command "info" SectionQuery
 		"shows  information about the specified item or the repository as a whole"
 		(paramRepeating paramItem) (seek <$$> optParser)

Command/List.hs

@@ -22,7 +22,7 @@ import Git.Types (RemoteName)
 import Utility.Tuple
 
 cmd :: Command
-cmd = noCommit $ withGlobalOptions annexedMatchingOptions $
+cmd = noCommit $ withGlobalOptions [annexedMatchingOptions] $
 	command "list" SectionQuery 
 		"show which remotes contain files"
 		paramPaths (seek <$$> optParser)

Command/Lock.hs

@@ -23,7 +23,7 @@ import Logs.Location
 import Git.FilePath
 	
 cmd :: Command
-cmd = notDirect $ withGlobalOptions (jsonOption : annexedMatchingOptions) $
+cmd = notDirect $ withGlobalOptions [jsonOptions, annexedMatchingOptions] $
 	command "lock" SectionCommon
 		"undo unlock command"
 		paramPaths (withParams seek)

Command/Log.hs

@@ -40,7 +40,7 @@ data LogChange = Added | Removed
 type Outputter = LogChange -> POSIXTime -> [UUID] -> Annex ()
 
 cmd :: Command
-cmd = withGlobalOptions annexedMatchingOptions $
+cmd = withGlobalOptions [annexedMatchingOptions] $
 	command "log" SectionQuery "shows location log"
 		paramPaths (seek <$$> optParser)
 

Command/MetaData.hs

@@ -23,7 +23,7 @@ import Data.Aeson
 import Control.Concurrent
 
 cmd :: Command
-cmd = withGlobalOptions ([jsonOption] ++ annexedMatchingOptions) $ 
+cmd = withGlobalOptions [jsonOptions, annexedMatchingOptions] $ 
 	command "metadata" SectionMetaData
 		"sets or gets metadata of a file"
 		paramPaths (seek <$$> optParser)

Command/Migrate.hs

@@ -20,7 +20,7 @@ import Logs.Web
 import qualified Remote
 
 cmd :: Command
-cmd = notDirect $ withGlobalOptions annexedMatchingOptions $
+cmd = notDirect $ withGlobalOptions [annexedMatchingOptions] $
 	command "migrate" SectionUtility 
 		"switch data to different backend"
 		paramPaths (withParams seek)

Command/Mirror.hs

@@ -17,7 +17,7 @@ import Annex.NumCopies
 import Types.Transfer
 
 cmd :: Command
-cmd = withGlobalOptions (jobsOption : jsonOption : jsonProgressOption : annexedMatchingOptions) $
+cmd = withGlobalOptions [jobsOption, jsonOptions, jsonProgressOption, annexedMatchingOptions] $
 	command "mirror" SectionCommon 
 		"mirror content of files to/from another repository"
 		paramPaths (seek <--< optParser)

Command/Move.hs

@@ -20,7 +20,7 @@ import Annex.NumCopies
 import System.Log.Logger (debugM)
 
 cmd :: Command
-cmd = withGlobalOptions (jobsOption : jsonOption : jsonProgressOption : annexedMatchingOptions) $
+cmd = withGlobalOptions [jobsOption, jsonOptions, jsonProgressOption, annexedMatchingOptions] $
 	command "move" SectionCommon
 		"move content of files to/from another repository"
 		paramPaths (seek <--< optParser)

Command/Status.hs

@@ -17,7 +17,7 @@ import Git.FilePath
 
 cmd :: Command
 cmd = notBareRepo $ noCommit $ noMessages $
-	withGlobalOptions [jsonOption] $
+	withGlobalOptions [jsonOptions] $
 		command "status" SectionCommon
 			"show the working tree status"
 			paramPaths (seek <$$> optParser)

Command/Unannex.hs

@@ -24,7 +24,7 @@ import qualified Database.Keys
 import Git.FilePath
 
 cmd :: Command
-cmd = withGlobalOptions annexedMatchingOptions $
+cmd = withGlobalOptions [annexedMatchingOptions] $
 	command "unannex" SectionUtility
 		"undo accidental add command"
 		paramPaths (withParams seek)

Command/Unlock.hs

@@ -26,8 +26,9 @@ editcmd :: Command
 editcmd = mkcmd "edit" "same as unlock"
 
 mkcmd :: String -> String -> Command
-mkcmd n d = notDirect $ withGlobalOptions (jsonOption : annexedMatchingOptions) $
+mkcmd n d = notDirect $ 
-	command n SectionCommon d paramPaths (withParams seek)
+	withGlobalOptions [jsonOptions, annexedMatchingOptions] $
+		command n SectionCommon d paramPaths (withParams seek)
 
 seek :: CmdParams -> CommandSeek
 seek ps = withFilesInGit (whenAnnexed start) =<< workTreeItems ps

Command/Whereis.hs

@@ -17,7 +17,7 @@ import Annex.UUID
 import qualified Data.Map as M
 
 cmd :: Command
-cmd = noCommit $ withGlobalOptions (jsonOption : annexedMatchingOptions) $
+cmd = noCommit $ withGlobalOptions [jsonOptions, annexedMatchingOptions] $
 	command "whereis" SectionQuery
 		"lists repositories that have file content"
 		paramPaths (seek <$$> optParser)

Types/Messages.hs

@@ -21,12 +21,14 @@ data OutputType = NormalOutput | QuietOutput | JSONOutput JSONOptions
 
 data JSONOptions = JSONOptions
 	{ jsonProgress :: Bool
+	, jsonErrorMessages :: Bool
 	}
 	deriving (Show)
 
 adjustOutputType :: OutputType -> OutputType -> OutputType
 adjustOutputType (JSONOutput old) (JSONOutput new) = JSONOutput $ JSONOptions
 	{ jsonProgress = jsonProgress old || jsonProgress new
+	, jsonErrorMessages = jsonErrorMessages old || jsonErrorMessages new
 	}
 adjustOutputType _old new = new
 

doc/git-annex-add.mdwn

@@ -66,6 +66,10 @@ annexed content, and other symlinks.
   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`
+
+  Include any error messages in the json, rather than output to stderr.
+
 * `--batch`
 
   Enables batch mode, in which a file to add is read in a line from stdin,

doc/git-annex-addurl.mdwn

@@ -97,6 +97,10 @@ be used to get better filenames.
 
   Include progress objects in JSON output.
 
+* `--json-error-messages`
+
+  Include any error messages in the json, rather than output to stderr.
+
 # CAVEATS
 
 If annex.largefiles is configured, and does not match a file, `git annex

doc/git-annex-copy.mdwn

@@ -97,6 +97,10 @@ Copies the content of files from or to another remote.
 
   Include progress objects in JSON output.
 
+* `--json-error-messages`
+
+  Include any error messages in the json, rather than output to stderr.
+
 # SEE ALSO
 
 [[git-annex]](1)

doc/git-annex-drop.mdwn

@@ -87,6 +87,10 @@ safe to do so.
   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`
+
+  Include any error messages in the json, rather than output to stderr.
+
 # SEE ALSO
 
 [[git-annex]](1)

doc/git-annex-dropkey.mdwn

@@ -29,6 +29,10 @@ exist; using it can easily result in data loss.
   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`
+
+  Include any error messages in the json, rather than output to stderr.
+
 # SEE ALSO
 
 [[git-annex]](1)

doc/git-annex-examinekey.mdwn

@@ -33,6 +33,10 @@ that can be determined purely by looking at the key.
   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`
+
+  Include any error messages in the json, rather than output to stderr.
+
 * `--batch`
 
   Enable batch mode, in which a line containing a key is read from stdin,

doc/git-annex-find.mdwn

@@ -54,6 +54,10 @@ finds files in the current directory and its subdirectories.
   This is intended to be parsed by programs that use
   git-annex. Each line of output is a JSON object.
 
+* `--json-error-messages`
+
+  Include any error messages in the json, rather than output to stderr.
+
 * `--batch`
 
   Enables batch mode, in which a file is read in a line from stdin,

doc/git-annex-fsck.mdwn

@@ -98,6 +98,10 @@ With parameters, only the specified files are checked.
   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`
+
+  Include any error messages in the json, rather than output to stderr.
+
 # OPTIONS
 
 # SEE ALSO

doc/git-annex-get.mdwn

@@ -106,6 +106,10 @@ or transferring them from some kind of key-value store.
 
   Include progress objects in JSON output.
 
+* `--json-error-messages`
+
+  Include any error messages in the json, rather than output to stderr.
+
 # SEE ALSO
 
 [[git-annex]](1)

doc/git-annex-import.mdwn

@@ -81,6 +81,10 @@ Several options can be used to adjust handling of duplicate files.
   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`
+
+  Include any error messages in the json, rather than output to stderr.
+
 # CAVEATS
 
 Note that using `--deduplicate` or `--clean-duplicates` with the WORM

doc/git-annex-info.mdwn

@@ -26,6 +26,10 @@ for the repository as a whole.
   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`
+
+  Include any error messages in the json, rather than output to stderr.
+
 * `--bytes`
 
   Show file sizes in bytes, disabling the default nicer units.

doc/git-annex-lock.mdwn

@@ -23,6 +23,10 @@ the files any longer, or have made modifications you want to discard.
   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`
+
+  Include any error messages in the json, rather than output to stderr.
+
 # SEE ALSO
 
 [[git-annex]](1)

doc/git-annex-metadata.mdwn

@@ -112,6 +112,10 @@ automatically.
 
 	{"command":"metadata","file":"foo","key":"...","author":["bar"],...,"note":"...","success":true}
 
+* `--json-error-messages`
+
+  Include any error messages in the json, rather than output to stderr.
+
 * `--batch`
 
   Enables batch mode, which can be used to both get, store, and unset

doc/git-annex-mirror.mdwn

@@ -75,6 +75,10 @@ contents. Use [[git-annex-sync]](1) for that.
 
   Include progress objects in JSON output.
 
+* `--json-error-messages`
+
+  Include any error messages in the json, rather than output to stderr.
+
 # SEE ALSO
 
 [[git-annex]](1)

doc/git-annex-move.mdwn

@@ -92,6 +92,10 @@ Moves the content of files from or to another remote.
 
   Include progress objects in JSON output.
 
+* `--json-error-messages`
+
+  Include any error messages in the json, rather than output to stderr.
+
 # SEE ALSO
 
 [[git-annex]](1)

doc/git-annex-status.mdwn

@@ -18,15 +18,19 @@ Particularly useful in direct mode.
 
 # OPTIONS
 
+* `--ignore-submodules=when`
+
+  This option is passed on to git status, see its man page for
+  details.
+
 * `--json`
 
   Enable JSON output. This is intended to be parsed by programs that use
   git-annex. Each line of output is a JSON object.
 
-* `--ignore-submodules=when`
+* `--json-error-messages`
 
-  This option is passed on to git status, see its man page for
+  Include any error messages in the json, rather than output to stderr.
-  details.
 
 # SEE ALSO
 

doc/git-annex-unlock.mdwn

@@ -42,6 +42,10 @@ file to be lost from the local repository. So, enable annex.thin with care.
   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`
+
+  Include any error messages in the json, rather than output to stderr.
+
 # SEE ALSO
 
 [[git-annex]](1)

doc/git-annex-whereis.mdwn

@@ -43,11 +43,6 @@ For example:
 
   Show whereis information for files found by last run of git-annex unused.
 
-* `--json`
-
-  Enable JSON output. This is intended to be parsed by programs that use
-  git-annex. Each line of output is a JSON object.
-
 * `--batch`
 
   Enables batch mode, in which a file is read in a line from stdin,
@@ -56,6 +51,15 @@ For example:
   Note that if the file is not an annexed file, an empty line will be
   output instead.
 
+* `--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`
+
+  Include any error messages in the json, rather than output to stderr.
+
 # SEE ALSO
 
 [[git-annex]](1)