From e10a3f164f9569d7ab68d176458c3594ccc09dac Mon Sep 17 00:00:00 2001
From: vilmibm <vilmibm@neongrid.space>
Date: Tue, 13 Apr 2021 22:43:02 -0500
Subject: [PATCH] minor usage improvements

---
 pkg/cmd/run/rerun/rerun.go          |  2 +-
 pkg/cmd/run/view/view.go            | 20 ++++++++++----------
 pkg/cmd/run/watch/watch.go          | 10 +++++++++-
 pkg/cmd/workflow/disable/disable.go |  1 +
 pkg/cmd/workflow/enable/enable.go   |  1 +
 pkg/cmd/workflow/list/list.go       |  3 ++-
 pkg/cmd/workflow/run/run.go         |  2 +-
 7 files changed, 25 insertions(+), 14 deletions(-)

diff --git a/pkg/cmd/run/rerun/rerun.go b/pkg/cmd/run/rerun/rerun.go
index 45bc320e1..16f940213 100644
--- a/pkg/cmd/run/rerun/rerun.go
+++ b/pkg/cmd/run/rerun/rerun.go
@@ -31,7 +31,7 @@ func NewCmdRerun(f *cmdutil.Factory, runF func(*RerunOptions) error) *cobra.Comm
 
 	cmd := &cobra.Command{
 		Use:   "rerun [<run-id>]",
-		Short: "Rerun a given run",
+		Short: "Rerun a failed run",
 		Args:  cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			// support `-R, --repo` override
diff --git a/pkg/cmd/run/view/view.go b/pkg/cmd/run/view/view.go
index 584c55634..131c73a82 100644
--- a/pkg/cmd/run/view/view.go
+++ b/pkg/cmd/run/view/view.go
@@ -91,20 +91,20 @@ func NewCmdView(f *cmdutil.Factory, runF func(*ViewOptions) error) *cobra.Comman
 		Short: "View a summary of a workflow run",
 		Args:  cobra.MaximumNArgs(1),
 		Example: heredoc.Doc(`
-		  # Interactively select a run to view, optionally drilling down to a job
-		  $ gh run view
-
-		  # View a specific run
-		  $ gh run view 12345
-
+			# Interactively select a run to view, optionally selecting a single job
+			$ gh run view
+			
+			# View a specific run
+			$ gh run view 12345
+			
 			# View a specific job within a run
 			$ gh run view --job 456789
-
+			
 			# View the full log for a specific job
 			$ gh run view --log --job 456789
-
-		  # Exit non-zero if a run failed
-		  $ gh run view 0451 --exit-status && echo "run pending or passed"
+			
+			# Exit non-zero if a run failed
+			$ gh run view 0451 --exit-status && echo "run pending or passed"
 		`),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			// support `-R, --repo` override
diff --git a/pkg/cmd/run/watch/watch.go b/pkg/cmd/run/watch/watch.go
index 69c34abf5..599dac345 100644
--- a/pkg/cmd/run/watch/watch.go
+++ b/pkg/cmd/run/watch/watch.go
@@ -7,6 +7,7 @@ import (
 	"runtime"
 	"time"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/cli/cli/api"
 	"github.com/cli/cli/internal/ghrepo"
 	"github.com/cli/cli/pkg/cmd/run/shared"
@@ -40,8 +41,15 @@ func NewCmdWatch(f *cmdutil.Factory, runF func(*WatchOptions) error) *cobra.Comm
 	}
 
 	cmd := &cobra.Command{
-		Use:   "watch <run-selector>",
+		Use:   "watch <run-id>",
 		Short: "Watch a run until it completes, showing its progress",
+		Example: heredoc.Doc(`
+			# Watch a run until it's done
+			gh run watch
+
+			# Run some other command when the run is finished
+			gh run watch && notify-send "run is done!"
+		`),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			// support `-R, --repo` override
 			opts.BaseRepo = f.BaseRepo
diff --git a/pkg/cmd/workflow/disable/disable.go b/pkg/cmd/workflow/disable/disable.go
index a55a88240..3b87d5599 100644
--- a/pkg/cmd/workflow/disable/disable.go
+++ b/pkg/cmd/workflow/disable/disable.go
@@ -31,6 +31,7 @@ func NewCmdDisable(f *cmdutil.Factory, runF func(*DisableOptions) error) *cobra.
 	cmd := &cobra.Command{
 		Use:   "disable [<workflow ID> | <workflow name>]",
 		Short: "Disable a workflow",
+		Long:  "Disable a workflow, preventing it from running or showing up when listing workflows.",
 		Args:  cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			// support `-R, --repo` override
diff --git a/pkg/cmd/workflow/enable/enable.go b/pkg/cmd/workflow/enable/enable.go
index 004a4adb5..775ec89f5 100644
--- a/pkg/cmd/workflow/enable/enable.go
+++ b/pkg/cmd/workflow/enable/enable.go
@@ -31,6 +31,7 @@ func NewCmdEnable(f *cmdutil.Factory, runF func(*EnableOptions) error) *cobra.Co
 	cmd := &cobra.Command{
 		Use:   "enable [<workflow ID> | <workflow name>]",
 		Short: "Enable a workflow",
+		Long:  "Enable a workflow, allowing it to be run and show up when listing workflows.",
 		Args:  cobra.MaximumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			// support `-R, --repo` override
diff --git a/pkg/cmd/workflow/list/list.go b/pkg/cmd/workflow/list/list.go
index d1f164436..94291bcc7 100644
--- a/pkg/cmd/workflow/list/list.go
+++ b/pkg/cmd/workflow/list/list.go
@@ -34,7 +34,8 @@ func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Comman
 
 	cmd := &cobra.Command{
 		Use:   "list",
-		Short: "List GitHub Actions workflows",
+		Short: "List workflows",
+		Long:  "List workflow files, hiding disabled workflows by default.",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			// support `-R, --repo` override
diff --git a/pkg/cmd/workflow/run/run.go b/pkg/cmd/workflow/run/run.go
index 6e732cb69..7669c174e 100644
--- a/pkg/cmd/workflow/run/run.go
+++ b/pkg/cmd/workflow/run/run.go
@@ -47,7 +47,7 @@ func NewCmdRun(f *cmdutil.Factory, runF func(*RunOptions) error) *cobra.Command
 
 	cmd := &cobra.Command{
 		Use:   "run [<workflow-ID> | <workflow-name>]",
-		Short: "Create a dispatch event for a workflow, starting a run",
+		Short: "Run a workflow by creating a workflow_dispatch event",
 		Long: heredoc.Doc(`
 			Create a workflow_dispatch event for a given workflow.