use flag placeholder value syntax

dev/sg/main.go

@@ -73,15 +73,15 @@ var sg = &cli.App{
 		},
 		&cli.StringFlag{
 			Name:        "config",
-			Usage:       "specify a sg configuration file",
+			Usage:       "load sg configuration from `file`",
 			EnvVars:     []string{"SG_CONFIG"},
 			TakesFile:   true,
 			Value:       defaultConfigFile,
 			Destination: &configFlag,
 		},
 		&cli.StringFlag{
 			Name:        "overwrite",
-			Usage:       "configuration overwrites file that is gitignored and can be used to, for example, add credentials",
+			Usage:       "load sg configuration from `file` that is gitignored and can be used to, for example, add credentials",
 			EnvVars:     []string{"SG_OVERWRITE"},
 			TakesFile:   true,
 			Value:       defaultConfigOverwriteFile,

dev/sg/sg_ci.go

@@ -36,14 +36,14 @@ var (
 	ciBranchFlag = cli.StringFlag{
 		Name:        "branch",
 		Aliases:     []string{"b"},
-		Usage:       "Branch name of build to target (defaults to current branch)",
+		Usage:       "Branch `name` of build to target (defaults to current branch)",
 		Destination: &ciBranch,
 	}
 
 	ciBuild     string
 	ciBuildFlag = cli.StringFlag{
 		Name:        "build",
-		Usage:       "Override branch detection with a specific build number",
+		Usage:       "Override branch detection with a specific build `number`",
 		Destination: &ciBuild,
 	}
 )
@@ -235,7 +235,7 @@ Learn more about pipeline run types in https://docs.sourcegraph.com/dev/backgrou
 			&cli.StringFlag{
 				Name:    "commit",
 				Aliases: []string{"c"},
-				Usage:   "commit from the current branch to build (defaults to current commit)",
+				Usage:   "`commit` from the current branch to build (defaults to current commit)",
 			},
 			&cli.BoolFlag{
 				Name:    "force",
@@ -369,20 +369,19 @@ From there, you can start exploring logs with the Grafana explore panel.
 			&cli.StringFlag{
 				Name:    "state",
 				Aliases: []string{"s"},
-				Usage:   "Job states to export logs for",
+				Usage:   "Job `state` to export logs for (provide an empty value for all states)",
 				Value:   "failed",
 			},
-
 			&cli.StringFlag{
 				Name:    "out",
 				Aliases: []string{"o"},
-				Usage: fmt.Sprintf("Output format: one of %+v, or a URL pointing to a Loki instance, such as %q",
+				Usage: fmt.Sprintf("Output `format`: one of %+v, or a URL pointing to a Loki instance, such as %q",
 					[]string{ciLogsOutTerminal, ciLogsOutSimple, ciLogsOutJSON}, loki.DefaultLokiURL),
 				Value: ciLogsOutTerminal,
 			},
 			&cli.StringFlag{
 				Name:  "overwrite-state",
-				Usage: "State to overwrite the job state metadata",
+				Usage: "`state` to overwrite the job state metadata",
 			},
 		},
 		Action: func(cmd *cli.Context) error {

dev/sg/sg_migration.go

@@ -29,7 +29,7 @@ var (
 	migrateTargetDatabase     string
 	migrateTargetDatabaseFlag = &cli.StringFlag{
 		Name:        "db",
-		Usage:       "The target database schema to modify",
+		Usage:       "The target database `schema` to modify",
 		Value:       db.DefaultDatabase.Name,
 		Destination: &migrateTargetDatabase,
 	}

dev/sg/sg_ops.go

@@ -38,23 +38,23 @@ var (
 		Flags: []cli.Flag{
 			&cli.StringFlag{
 				Name:        "kind",
-				Usage:       "The kind of deployment (one of 'k8s', 'helm')",
+				Usage:       "the `kind` of deployment (one of 'k8s', 'helm')",
 				Value:       string(images.DeploymentTypeK8S),
 				Destination: &opsUpdateImagesDeploymentKindFlag,
 			},
 			&cli.StringFlag{
 				Name:        "cr-username",
-				Usage:       "Username for the container registry",
+				Usage:       "`username` for the container registry",
 				Destination: &opsUpdateImagesContainerRegistryUsernameFlag,
 			},
 			&cli.StringFlag{
 				Name:        "cr-password",
-				Usage:       "Password or access token for the container registry",
+				Usage:       "`password` or access token for the container registry",
 				Destination: &opsUpdateImagesContainerRegistryPasswordFlag,
 			},
 			&cli.StringFlag{
 				Name:        "pin-tag",
-				Usage:       "Pin all images to a specific sourcegraph tag (e.g. 3.36.2, insiders)",
+				Usage:       "pin all images to a specific sourcegraph `tag` (e.g. 3.36.2, insiders)",
 				Destination: &opsUpdateImagesPinTagFlag,
 			},
 		},

internal/database/migration/cliutil/addlog.go

@@ -15,12 +15,12 @@ func AddLog(commandName string, factory RunnerFactory, out *output.Output) *cli.
 	flags := []cli.Flag{
 		&cli.StringFlag{
 			Name:     "db",
-			Usage:    `The target schema to modify.`,
+			Usage:    "The target `schema` to modify.",
 			Required: true,
 		},
 		&cli.IntFlag{
 			Name:     "version",
-			Usage:    "The migration version.",
+			Usage:    "The migration `version` to log.",
 			Required: true,
 		},
 		&cli.BoolFlag{

internal/database/migration/cliutil/downto.go

@@ -16,7 +16,7 @@ func DownTo(commandName string, factory RunnerFactory, out *output.Output, devel
 	flags := []cli.Flag{
 		&cli.StringFlag{
 			Name:     "db",
-			Usage:    `The target schema to modify.`,
+			Usage:    "The target `schema` to modify.",
 			Required: true,
 		},
 		&cli.StringFlag{

internal/database/migration/cliutil/undo.go

@@ -14,7 +14,7 @@ func Undo(commandName string, factory RunnerFactory, out *output.Output, develop
 	flags := []cli.Flag{
 		&cli.StringFlag{
 			Name:     "db",
-			Usage:    `The target schema to modify.`,
+			Usage:    "The target `schema` to modify.",
 			Required: true,
 		},
 		&cli.BoolFlag{

internal/database/migration/cliutil/up.go

@@ -17,7 +17,7 @@ func Up(commandName string, factory RunnerFactory, out *output.Output, developme
 	flags := []cli.Flag{
 		&cli.StringFlag{
 			Name:  "db",
-			Usage: `The target schema(s) to modify. Comma-separated values are accepted. Supply "all" (the default) to migrate all schemas.`,
+			Usage: "The target `schema(s)` to modify. Comma-separated values are accepted. Supply \"all\" to migrate all schemas.",
 			Value: "all",
 		},
 		&cli.BoolFlag{

internal/database/migration/cliutil/upto.go

@@ -16,12 +16,12 @@ func UpTo(commandName string, factory RunnerFactory, out *output.Output, develop
 	flags := []cli.Flag{
 		&cli.StringFlag{
 			Name:     "db",
-			Usage:    `The target schema to modify.`,
+			Usage:    "The target `schema` to modify.",
 			Required: true,
 		},
 		&cli.StringFlag{
 			Name:     "target",
-			Usage:    `The migration to apply. Comma-separated values are accepted.`,
+			Usage:    "The `migration` to apply. Comma-separated values are accepted.",
 			Required: true,
 		},
 		&cli.BoolFlag{

internal/database/migration/cliutil/validate.go

@@ -15,7 +15,7 @@ func Validate(commandName string, factory RunnerFactory, out *output.Output) *cl
 	flags := []cli.Flag{
 		&cli.StringFlag{
 			Name:  "db",
-			Usage: `The target schema(s) to modify. Comma-separated values are accepted. Supply "all" (the default) to migrate all schemas.`,
+			Usage: "The target `schema(s)` to modify. Comma-separated values are accepted. Supply \"all\" to migrate all schemas.",
 			Value: "all",
 		},
 	}