initremote --describe-other-params

Does not yet include descriptions from external special remote programs.

Annex/SpecialRemote.hs

@@ -72,7 +72,10 @@ findType config = maybe unspecified (specified . fromProposedAccepted) $
   where
 	unspecified = Left "Specify the type of remote with type="
 	specified s = case filter (findtype s) remoteTypes of
-		[] -> Left $ "Unknown remote type " ++ s
+		[] -> Left $ "Unknown remote type " ++ s 
+			++ " (pick from: "
+			++ intercalate " " (map typename remoteTypes)
+			++ ")"
 		(t:_) -> Right t
 	findtype s i = typename i == s
 

CHANGELOG

@@ -6,10 +6,12 @@ git-annex (7.20191231) UNRELEASED; urgency=medium
   * reinject --known: Fix bug that prevented it from working in a bare repo.
   * Support being used in a git repository that uses sha256 rather than sha1.
   * initremote, enableremote: Be stricter about rejecting invalid
-    configurations for remotes, particularly things like foo=true when
-    foo=yes is expected
-  * initremote, enableremote: Reject unknown parameters provided to these
-    commands.
+    configuration parameters for remotes, particularly things like foo=true
+    when foo=yes is expected.
+  * initremote, enableremote: Reject unknown configuration parameters
+    provided to these commands.
+  * initremote: Added --describe-other-params option, to show additional
+    configuration parameters you might want to set.
   * Added LISTCONFIGS to external special remote protocol. Special remote
     programs that use GETCONFIG/SETCONFIG are recommended to implement it.
 

CmdLine/Usage.hs

@@ -96,8 +96,8 @@ paramItem :: String
 paramItem = "ITEM"
 paramTreeish :: String
 paramTreeish = "TREEISH"
-paramKeyValue :: String
-paramKeyValue = "K=V"
+paramParamValue :: String
+paramParamValue = "PARAM=VALUE"
 paramNothing :: String
 paramNothing = ""
 paramRepeating :: String -> String

Command/EnableRemote.hs

@@ -31,7 +31,7 @@ import qualified Data.Map as M
 cmd :: Command
 cmd = command "enableremote" SectionSetup
 	"enables git-annex to use a remote"
-	(paramPair paramName $ paramOptional $ paramRepeating paramKeyValue)
+	(paramPair paramName $ paramOptional $ paramRepeating paramParamValue)
 	(withParams seek)
 
 seek :: CmdParams -> CommandSeek

Command/InitRemote.hs

@@ -16,6 +16,7 @@ import Annex.SpecialRemote
 import qualified Remote
 import qualified Logs.Remote
 import qualified Types.Remote as R
+import Types.RemoteConfig
 import Annex.UUID
 import Logs.UUID
 import Logs.Remote
@@ -26,18 +27,24 @@ import Config
 cmd :: Command
 cmd = command "initremote" SectionSetup
 	"creates a special (non-git) remote"
-	(paramPair paramName $ paramOptional $ paramRepeating paramKeyValue)
+	(paramPair paramName $ paramOptional $ paramRepeating paramParamValue)
 	(seek <$$> optParser)
 
 data InitRemoteOptions = InitRemoteOptions
 	{ cmdparams :: CmdParams
 	, sameas :: Maybe (DeferredParse UUID)
+	, describeOtherParams :: Bool
 	}
 
 optParser :: CmdParamsDesc -> Parser InitRemoteOptions
 optParser desc = InitRemoteOptions
 	<$> cmdParams desc
 	<*> optional parseSameasOption
+	<*> switch
+		( long "describe-other-params"
+		<> short 'p'
+		<> help "describe other configuration parameters for a special remote"
+		)
 
 parseSameasOption :: Parser (DeferredParse UUID)
 parseSameasOption = parseUUIDOption <$> strOption
@@ -67,8 +74,11 @@ start o (name:ws) = ifM (isJust <$> findExisting name)
 					(Logs.Remote.keyValToConfig Proposed ws)
 					<$> readRemoteLog
 				t <- either giveup return (findType c)
-				starting "initremote" (ActionItemOther (Just name)) $
-					perform t name c o
+				if describeOtherParams o
+					then startingCustomOutput (ActionItemOther Nothing) $
+						describeOtherParamsFor c t
+					else starting "initremote" (ActionItemOther (Just name)) $
+						perform t name c o
 			)
 	)
 
@@ -100,3 +110,26 @@ cleanup u name c o = do
 			setConfig (remoteConfig c "config-uuid") (fromUUID cu)
 			Logs.Remote.configSet cu c
 	return True
+
+describeOtherParamsFor :: RemoteConfig -> RemoteType -> CommandPerform
+describeOtherParamsFor c t = do
+	cp <- R.configParser t c
+	let l = mapMaybe mk $ filter notinconfig $ remoteConfigFieldParsers cp
+	liftIO $ forM_ l $ \(p, pd, vd) -> do
+		putStrLn p
+		putStrLn ("\t" ++ pd)
+		case vd of
+			Nothing -> return ()
+			Just vd' -> putStrLn $ "\t(" ++ vd' ++ ")"
+	next $ return True
+  where
+	notinconfig fp = not (M.member (parserForField fp) c)
+	mk fp = case fieldDesc fp of
+		HiddenField -> Nothing
+		FieldDesc d -> Just
+			( fromProposedAccepted (parserForField fp)
+			, d
+			, case valueDesc fp of
+				Nothing -> Nothing
+				Just (ValueDesc vd) -> Just vd
+			)

doc/git-annex-initremote.mdwn

@@ -20,15 +20,12 @@ For a list and details, see <https://git-annex.branchable.com/special_remotes/>
 The remote's configuration is specified by the parameters passed
 to this command. Different types of special remotes need different
 configuration values, so consult the documentation of a special remote for
-details. The command will prompt for any required parameters you leave out.
+details. The command will prompt for any required parameters you leave out;
+you can also pass --describe-other-params to see additional parameters.
+
 A few parameters that are supported by all special remotes are documented in
 the next section below.
 
-To list all the configuration parameters that are accepted by a particular
-type of special remote, along with short descriptions, run eg:
-
-	git annex initremote --list-params-for=S3
-
 Once a special remote has been initialized once with this command,
 other clones of the repository can also be set up to access it using
 `git annex enableremote`.
@@ -41,10 +38,14 @@ want to use `git annex renameremote`.
 
 # OPTIONS
 
-* `--list-params-for=type`
+* `--describe-other-params` / `-p`
 
-  Lists all configuration parameters that are accepted for a given
-  type of special remote.
+  Describe additional configuration parameters that you could specify.
+
+  For example, if you know you want a S3 remote, but forget how to
+  configure it:
+
+	git annex initremote mys3 type=S3 --describe-other-params
 
 * `--fast`
 
@@ -87,6 +88,7 @@ want to use `git annex renameremote`.
   
   For details about this and other encrpytion settings, see
   <https://git-annex.branchable.com/encryption/>
+  or --describe-other-params
 
 * `autoenable`