Merge pull request #533 from docker/feat/pass-docs

refactor(pass): extract multi-line Long descriptions to embedded mark down

Author: joe0BAB

plugins/pass/command.go

@@ -53,19 +53,15 @@ Examples:
 //go:embed examples.md
 var rootExample string
 
+//go:embed long.md
+var rootLong string
+
 // Root returns the root command for the docker-pass CLI plugin
 func Root(ctx context.Context, s store.Store, info commands.VersionInfo) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "pass set|get|ls|rm|run",
-		Short: "Manage your local OS keychain secrets.",
-		Long: "Docker Pass is a helper for securely storing secrets in your local OS keychain and injecting them into containers when needed.\n" +
-			"It uses platform-specific credential storage:\n" +
-			"\n" +
-			"  - Windows: Windows Credential Manager API\n" +
-			"  - macOS:   Keychain services API\n" +
-			"  - Linux:   `org.freedesktop.secrets` API (requires DBus + `gnome-keyring` or `kdewallet`)\n" +
-			"\n" +
-			"Secrets can be injected into running containers at runtime using the `se://` URI scheme.",
+		Use:              "pass set|get|ls|rm|run",
+		Short:            "Manage your local OS keychain secrets.",
+		Long:             strings.TrimSpace(rootLong),
 		Example:          strings.TrimSpace(rootExample),
 		SilenceUsage:     true,
 		TraverseChildren: true,

plugins/pass/commands/run.go

@@ -52,24 +52,19 @@ func (e *ExitCodeError) Error() string {
 //go:embed run_example.md
 var runExample string
 
+//go:embed run_long.md
+var runLong string
+
 type runOpts struct {
 	envFiles []string
 }
 
 func RunCommand() *cobra.Command {
 	opts := runOpts{}
 	cmd := &cobra.Command{
-		Use:   "run -- CMD [ARGS...]",
-		Short: "Run a command with `se://` environment references resolved.",
-		Long: "Scans the current environment (plus any `--env-file` inputs) for variables\n" +
-			"whose value is exactly `se://<ID|pattern>`. Each reference is resolved through the\n" +
-			"secrets-engine daemon and the resolved value is passed to the child process.\n" +
-			"The child inherits stdin, stdout, and stderr.\n" +
-			"\n" +
-			"Requires the secrets-engine daemon (Docker Desktop) to be running.\n" +
-			"\n" +
-			"If any reference cannot be resolved, the command fails before the child is\n" +
-			"started and exits non-zero.",
+		Use:     "run -- CMD [ARGS...]",
+		Short:   "Run a command with `se://` environment references resolved.",
+		Long:    strings.Trim(runLong, "\n"),
 		Example: strings.Trim(runExample, "\n"),
 		Args:    cobra.MinimumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {

plugins/pass/commands/run_long.md

@@ -0,0 +1,9 @@
+Scans the current environment (plus any `--env-file` inputs) for variables
+whose value is exactly `se://<ID|pattern>`. Each reference is resolved through the
+secrets-engine daemon and the resolved value is passed to the child process.
+The child inherits stdin, stdout, and stderr.
+
+Requires the secrets-engine daemon (Docker Desktop) to be running.
+
+If any reference cannot be resolved, the command fails before the child is
+started and exits non-zero.

plugins/pass/commands/set.go

@@ -33,6 +33,9 @@ import (
 //go:embed set_example.md
 var setExample string
 
+//go:embed set_long.md
+var setLong string
+
 type setOpts struct {
 	metadata []string // raw "key=value" strings from --metadata flag
 	force    bool     // if true, overwrite existing secret instead of erroring
@@ -49,16 +52,7 @@ func SetCommand(kc store.Store) *cobra.Command {
 		Use:     "set id[=value]",
 		Aliases: []string{"store", "save"},
 		Short:   "Set a secret",
-		Long: "Stores a secret in the local OS keychain. The secret value can be provided inline (`NAME=VALUE`) or piped via STDIN.\n" +
-			"\n" +
-			"Behavior when a secret with the same id already exists is platform-dependent:\n" +
-			"  - macOS (Keychain): the command fails with a duplicate-item error.\n" +
-			"  - Linux (Secret Service) and Windows (Credential Manager): the existing\n" +
-			"    value is silently overwritten.\n" +
-			"\n" +
-			"Pass `--force` to overwrite an existing secret. On Linux and Windows the\n" +
-			"replacement is performed atomically. On macOS the Keychain API requires\n" +
-			"a delete-then-add sequence.",
+		Long:    strings.Trim(setLong, "\n"),
 		Example: strings.Trim(setExample, "\n"),
 		Args:    cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {

plugins/pass/commands/set_long.md

@@ -0,0 +1,10 @@
+Stores a secret in the local OS keychain. The secret value can be provided inline (`NAME=VALUE`) or piped via STDIN.
+
+Behavior when a secret with the same id already exists is platform-dependent:
+  - macOS (Keychain): the command fails with a duplicate-item error.
+  - Linux (Secret Service) and Windows (Credential Manager): the existing
+    value is silently overwritten.
+
+Pass `--force` to overwrite an existing secret. On Linux and Windows the
+replacement is performed atomically. On macOS the Keychain API requires
+a delete-then-add sequence.

plugins/pass/long.md

@@ -0,0 +1,8 @@
+Docker Pass is a helper for securely storing secrets in your local OS keychain and injecting them into containers when needed.
+It uses platform-specific credential storage:
+
+  - Windows: Windows Credential Manager API
+  - macOS:   Keychain services API
+  - Linux:   `org.freedesktop.secrets` API (requires DBus + `gnome-keyring` or `kdewallet`)
+
+Secrets can be injected into running containers at runtime using the `se://` URI scheme.