chore/sg: clean up help formatting (#63860)

Noticed several `Usage` using newlines, which makes `-h` output pretty
annoying to read as it breaks up the formatting. It tickled me enough to
put a formatting check against it, and update the existing usages that
were incorrect, to use `Description` or `UsageText` instead :-)

## Test plan

CI, `sg -h` is pretty(er) again (but still very long)

dev/sg/main_test.go

@@ -51,6 +51,7 @@ func testCommandFormatting(t *testing.T, cmd *cli.Command) {
 	t.Run(cmd.Name, func(t *testing.T) {
 		assert.NotEmpty(t, cmd.Name, "Name should be set")
 		assert.NotEmpty(t, cmd.Usage, "Usage should be set")
+		assert.False(t, strings.Contains(cmd.Usage, "\n"), "Usage should not have new lines - use Description or UsageText instead")
 		assert.False(t, strings.HasSuffix(cmd.Usage, "."), "Usage should not end with period")
 		if len(cmd.Subcommands) == 0 {
 			assert.NotNil(t, cmd.Action, "Action must be provided for command without subcommands")

dev/sg/sg_backport.go

@@ -25,9 +25,10 @@ var releaseBranchFlag = cli.StringFlag{
 }
 
 var backportCommand = &cli.Command{
-	Name:     "backport",
-	Category: category.Dev,
-	Usage:    "Backport commits from main to release branches.\nsg backport -r 5.3 -p 60932",
+	Name:      "backport",
+	Category:  category.Dev,
+	Usage:     "Backport commits from main to release branches",
+	UsageText: "sg backport -r 5.3 -p 60932",
 	Action: func(cmd *cli.Context) error {
 		prNumber := pullRequestIDFlag.Get(cmd)
 		releaseBranch := releaseBranchFlag.Get(cmd)

dev/sg/sg_images.go

@@ -11,6 +11,7 @@ import (
 	"github.com/urfave/cli/v2"
 
 	"github.com/sourcegraph/run"
+
 	"github.com/sourcegraph/sourcegraph/dev/sg/internal/category"
 	"github.com/sourcegraph/sourcegraph/dev/sg/internal/std"
 	"github.com/sourcegraph/sourcegraph/lib/errors"
@@ -47,8 +48,15 @@ var imagesCommand = &cli.Command{
 		},
 		{
 			Name:      "build",
-			Usage:     "builds a container image by matching [pattern] using glob syntax to the target.\nExamples:\n- sg images build worker\n- sg images build cmd/*\n- sg images build postgres*",
-			UsageText: "build [pattern1] ([pattern2] ...)",
+			Usage:     "builds a container image by matching [pattern] using glob syntax to the target",
+			ArgsUsage: "build [pattern1] ([pattern2] ...)",
+			UsageText: `
+sg images build worker
+# Build everything under 'cmd/*'
+sg images build cmd/*
+# Build all postgres images
+sg images build postgres*
+`,
 			Flags: []cli.Flag{
 				&cli.BoolFlag{
 					Name:  "load",

dev/sg/sg_run.go

@@ -14,7 +14,7 @@ import (
 	"github.com/sourcegraph/sourcegraph/lib/cliutil/completions"
 )
 
-var deprecationNotice = "sg run is deprecated. Use 'sg start -cmd' instead.\n"
+var deprecationNotice = "[DEPRECATED] sg run is deprecated - use 'sg start -cmd' instead"
 
 func init() {
 	postInitHooks = append(postInitHooks,
@@ -34,10 +34,11 @@ func init() {
 }
 
 var runCommand = &cli.Command{
-	Name:      "run",
-	Usage:     deprecationNotice,
-	ArgsUsage: "[command]",
-	UsageText: deprecationNotice + `
+	Name:        "run",
+	Usage:       deprecationNotice,
+	ArgsUsage:   "[command]",
+	Description: deprecationNotice,
+	UsageText: `
 # Run specific commands
 sg run gitserver
 sg run frontend