Go back and update Gitaly CLI for new style guide updates

8 files changed, 40 insertions, 21 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c1f79f8d5..359664231 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -40,9 +40,11 @@ reported by emailing contact@gitlab.com.
 This Code of Conduct is adapted from the [Contributor Covenant](https://contributor-covenant.org), version 1.1.0,
 available at [https://contributor-covenant.org/version/1/1/0/](https://contributor-covenant.org/version/1/1/0/).
 
-## Style Guide
+## Style guides
 
-The Gitaly style guide is [documented in it's own file](STYLE.md).
+For Gitaly code style, see [`STYLE.md`](STYLE.md).
+
+For help text style guidance for this project, see the [help text style guide](doc/help_text_style_guide.md).
 
 ## Commits
 
@@ -63,7 +65,7 @@ not be focused enough.
 
 `git add -p` is useful to add only relevant changes. Often you only notice that
 you require additional changes to achieve your goal when halfway through the
-implementation.  Use `git stash` to help you stay focused on this additional
+implementation. Use `git stash` to help you stay focused on this additional
 change until you have implemented it in a separate commit.
 
 ### Split up refactors and behavioral changes
diff --git a/cmd/gitaly/main_test.go b/cmd/gitaly/main_test.go
index 3c70d9ed9..2c820f84f 100644
--- a/cmd/gitaly/main_test.go
+++ b/cmd/gitaly/main_test.go
@@ -30,7 +30,7 @@ func TestGitalyCLI(t *testing.T) {
 		{
 			desc:     "without arguments",
 			exitCode: 2,
-			stdout:   "NAME:\n   gitaly - A Git RPC service\n\nUSAGE:\n   gitaly command [command options] [arguments...]\n\nDESCRIPTION:\n   Gitaly is a Git RPC service for handling Git calls.\n\nCOMMANDS:\n   serve          Launch the server daemon\n   check          Verify internal API is accessible\n   configuration  Run configuration-related commands\n   hooks          Manage Git hooks\n\nOPTIONS:\n   --help, -h     show help\n   --version, -v  print the version\n",
+			stdout:   "NAME:\n   gitaly - a Git RPC service\n\nUSAGE:\n   gitaly command [command options] [arguments...]\n\nDESCRIPTION:\n   Gitaly is a Git RPC service for handling Git calls.\n\nCOMMANDS:\n   serve          launch the server daemon\n   check          verify internal API is accessible\n   configuration  run configuration-related commands\n   hooks          manage Git hooks\n\nOPTIONS:\n   --help, -h     show help\n   --version, -v  print the version\n",
 		},
 		{
 			desc:     "with non-existent config",
@@ -42,7 +42,7 @@ func TestGitalyCLI(t *testing.T) {
 			desc:     "check without config",
 			args:     []string{"check"},
 			exitCode: 2,
-			stdout:   "NAME:\n   gitaly check - Verify internal API is accessible\n\nUSAGE:\n   gitaly check command [command options] <configfile>\n\nDESCRIPTION:\n   Check that the internal Gitaly API is accessible.\n\nOPTIONS:\n   --help, -h  show help\n",
+			stdout:   "NAME:\n   gitaly check - verify internal API is accessible\n\nUSAGE:\n   gitaly check command [command options] <configfile>\n\nDESCRIPTION:\n   Check that the internal Gitaly API is accessible.\n\n   Example: `gitaly check gitaly.config.toml`.\n\nOPTIONS:\n   --help, -h  show help\n",
 			stderr:   "invalid argument(s)",
 		},
 		{
diff --git a/doc/help_text_style_guide.md b/doc/help_text_style_guide.md
index f7e028961..b11654f4d 100644
--- a/doc/help_text_style_guide.md
+++ b/doc/help_text_style_guide.md
@@ -93,8 +93,17 @@ When providing values for the `Description` field key:
   Runs all of the processes for the Gitaly Cluster.
   ```
 
+If the command or subcommand requires more than just flags, add an example of invoking the command. For example:
+
+```go
+Description: "The subcommand accepts a file on stdin.\n\n" +
+
+             "Example: `command subcommand < file`." +
+```
+
 ## Related topics
 
 - [Voice and tone](https://design.gitlab.com/content/voice-and-tone) from GitLab Design System.
 - [Language](https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#language) from GitLab
   Documentation Style Guide.
+- [Command Line Interface Guidelines](https://clig.dev).
diff --git a/internal/cli/gitaly/app.go b/internal/cli/gitaly/app.go
index b5cdad174..50bb3b7f3 100644
--- a/internal/cli/gitaly/app.go
+++ b/internal/cli/gitaly/app.go
@@ -19,7 +19,7 @@ func init() {
 func NewApp() *cli.App {
 	return &cli.App{
 		Name:        "gitaly",
-		Usage:       "A Git RPC service",
+		Usage:       "a Git RPC service",
 		Description: "Gitaly is a Git RPC service for handling Git calls.",
 		Version:     version.GetVersionString("Gitaly"),
 		// serveAction is also here in the root to keep the CLI backwards compatible
diff --git a/internal/cli/gitaly/check.go b/internal/cli/gitaly/check.go
index bba97f908..9c0c3932b 100644
--- a/internal/cli/gitaly/check.go
+++ b/internal/cli/gitaly/check.go
@@ -15,9 +15,11 @@ import (
 
 func newCheckCommand() *cli.Command {
 	return &cli.Command{
-		Name:            "check",
-		Usage:           "Verify internal API is accessible",
-		Description:     "Check that the internal Gitaly API is accessible.",
+		Name:  "check",
+		Usage: "verify internal API is accessible",
+		Description: "Check that the internal Gitaly API is accessible.\n\n" +
+
+			"Example: `gitaly check gitaly.config.toml`.",
 		ArgsUsage:       "<configfile>",
 		Action:          checkAction,
 		HideHelpCommand: true,
diff --git a/internal/cli/gitaly/configuration-validate.go b/internal/cli/gitaly/configuration-validate.go
index a3cd0e25f..e53710b6a 100644
--- a/internal/cli/gitaly/configuration-validate.go
+++ b/internal/cli/gitaly/configuration-validate.go
@@ -12,7 +12,7 @@ const validationErrorCode = 2
 func newConfigurationCommand() *cli.Command {
 	return &cli.Command{
 		Name:  "configuration",
-		Usage: "Run configuration-related commands",
+		Usage: "run configuration-related commands",
 		Description: "Run commands related to Gitaly configuration.\n\n" +
 
 			"Provides the following subcommand:\n\n" +
@@ -22,7 +22,7 @@ func newConfigurationCommand() *cli.Command {
 		Subcommands: []*cli.Command{
 			{
 				Name:  "validate",
-				Usage: "Validate Gitaly configuration",
+				Usage: "validate Gitaly configuration",
 				Description: "Check that input provided on stdin is valid Gitaly configuration.\n" +
 					"Use `validate` before starting Gitaly.\n\n" +
 
@@ -31,7 +31,9 @@ func newConfigurationCommand() *cli.Command {
 
 					"- A key, which is the path to the configuration field where the\n" +
 					"  problem is detected.\n" +
-					"- A message, with an explanation of the problem.",
+					"- A message, with an explanation of the problem.\n\n" +
+
+					"Example: `gitaly configuration validate < gitaly.config.toml`.",
 				Action: validateConfigurationAction,
 			},
 		},
diff --git a/internal/cli/gitaly/hooks.go b/internal/cli/gitaly/hooks.go
index 31dd5b843..d1ced6462 100644
--- a/internal/cli/gitaly/hooks.go
+++ b/internal/cli/gitaly/hooks.go
@@ -28,7 +28,7 @@ const (
 func newHooksCommand() *cli.Command {
 	return &cli.Command{
 		Name:  "hooks",
-		Usage: "Manage Git hooks",
+		Usage: "manage Git hooks",
 		Description: "Manage hooks for a Git repository.\n\n" +
 
 			"Provides the following subcommand:\n\n" +
@@ -37,23 +37,27 @@ func newHooksCommand() *cli.Command {
 		HideHelpCommand: true,
 		Subcommands: []*cli.Command{
 			{
-				Name:        "set",
-				Usage:       "Set custom hooks for a Git repository",
-				Description: "Reads a tarball containing custom Git hooks from stdin and writes the hooks to the specified repository.",
-				Action:      setHooksAction,
+				Name:  "set",
+				Usage: "set custom hooks for a Git repository",
+				Description: "Reads a tarball containing custom Git hooks from stdin and writes the hooks to the specified repository.\n\n" +
+
+					"Example: `gitaly hooks set --storage default --repository @hashed/<path_to_git_repository>/repository.git --config gitaly.config.toml < hooks_tarball.tar`.\n\n" +
+
+					"To remove custom Git hooks for a specified repository, run the set subcommand with an empty tarball file.",
+				Action: setHooksAction,
 				Flags: []cli.Flag{
 					&cli.StringFlag{
 						Name:  flagStorage,
-						Usage: "Storage containing the repository",
+						Usage: "storage containing the repository",
 					},
 					&cli.StringFlag{
 						Name:     flagRepository,
-						Usage:    "Repository to set hooks for",
+						Usage:    "repository to set hooks for",
 						Required: true,
 					},
 					&cli.StringFlag{
 						Name:     flagConfig,
-						Usage:    "Path to Gitaly configuration",
+						Usage:    "path to Gitaly configuration",
 						Aliases:  []string{"c"},
 						Required: true,
 					},
diff --git a/internal/cli/gitaly/serve.go b/internal/cli/gitaly/serve.go
index 8ba00536a..093411f88 100644
--- a/internal/cli/gitaly/serve.go
+++ b/internal/cli/gitaly/serve.go
@@ -54,7 +54,7 @@ import (
 func newServeCommand() *cli.Command {
 	return &cli.Command{
 		Name:            "serve",
-		Usage:           "Launch the server daemon",
+		Usage:           "launch the server daemon",
 		Description:     "Launch the Gitaly server daemon.",
 		ArgsUsage:       "<configfile>",
 		Action:          serveAction,