From efa4d43cf4c800fb4646046f8410837505c5119e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mislav=20Marohni=C4=87?= <mislav@github.com>
Date: Tue, 20 Jul 2021 15:32:51 +0200
Subject: [PATCH] Simplify `alias set` documentation

---
 pkg/cmd/alias/set/set.go | 47 +++++++++++++++-------------------------
 1 file changed, 17 insertions(+), 30 deletions(-)

diff --git a/pkg/cmd/alias/set/set.go b/pkg/cmd/alias/set/set.go
index 1bc732742..9975b9173 100644
--- a/pkg/cmd/alias/set/set.go
+++ b/pkg/cmd/alias/set/set.go
@@ -34,49 +34,36 @@ func NewCmdSet(f *cmdutil.Factory, runF func(*SetOptions) error) *cobra.Command
 		Use:   "set <alias> <expansion>",
 		Short: "Create a shortcut for a gh command",
 		Long: heredoc.Doc(`
-			Declare a word as a command alias that will expand to the specified command(s).
+			Define a word that will expand to a full gh command when invoked.
 
-			The expansion may specify additional arguments and flags. If the expansion
-			includes positional placeholders such as '$1', '$2', etc., any extra arguments
-			that follow the invocation of an alias will be inserted appropriately.
-			Reads from STDIN if '-' is specified as the expansion parameter. This can be useful
-			for commands with mixed quotes or multiple lines.
+			The expansion may specify additional arguments and flags. If the expansion includes
+			positional placeholders such as "$1", extra arguments that follow the alias will be
+			inserted appropriately. Otherwise, extra arguments will be appended to the expanded
+			command.
 
-			If '--shell' is specified, the alias will be run through a shell interpreter (sh). This allows you
-			to compose commands with '|' or redirect with '>'. Note that extra arguments following the alias
-			will not be automatically passed to the expanded expression. To have a shell alias receive
-			arguments, you must explicitly accept them using '$1', '$2', etc., or '$@' to accept all of them.
+			Use "-" as expansion argument to read the expansion string from standard input. This
+			is useful to avoid quoting issues when defining expansions.
 
-			Quotes must always be used when defining a command as in the examples unless you pass '-'
-			as the expansion parameter and pipe your command to 'gh alias set'.
-
-			Platform notes for Windows:
-
-			- If you are using the Command Prompt (cmd.exe), use *double* quotes instead of single quotes.
-			  For instance, use` + " `gh alias set pv \"pr view\"` instead of `gh alias set pv 'pr view'`.  "),
+			If the expansion starts with "!" or if "--shell" was given, the expansion is a shell
+			expression that will be evaluated through the "sh" interpreter when the alias is
+			invoked. This allows for chaining multiple commands via piping and redirection.
+		`),
 		Example: heredoc.Doc(`
+			# note: Command Prompt on Windows requires using double quotes for arguments
 			$ gh alias set pv 'pr view'
-			$ gh pv -w 123
-			#=> gh pr view -w 123
+			$ gh pv -w 123  #=> gh pr view -w 123
 
-			$ gh alias set bugs 'issue list --label="bugs"'
+			$ gh alias set bugs 'issue list --label=bugs'
 			$ gh bugs
 
 			$ gh alias set homework 'issue list --assignee @me'
 			$ gh homework
 
 			$ gh alias set epicsBy 'issue list --author="$1" --label="epic"'
-			$ gh epicsBy vilmibm
-			#=> gh issue list --author="vilmibm" --label="epic"
+			$ gh epicsBy vilmibm  #=> gh issue list --author="vilmibm" --label="epic"
 
-			$ gh alias set --shell igrep 'gh issue list --label="$1" | grep $2'
-			$ gh igrep epic foo
-			#=> gh issue list --label="epic" | grep "foo"
-
-			# users.txt contains multiline 'api graphql -F name="$1" ...' with mixed quotes
-			$ gh alias set users - < users.txt
-			$ gh users octocat
-			#=> gh api graphql -F name="octocat" ...
+			$ gh alias set --shell igrep 'gh issue list --label="$1" | grep "$2"'
+			$ gh igrep epic foo  #=> gh issue list --label="epic" | grep "foo"
 		`),
 		Args: cobra.ExactArgs(2),
 		RunE: func(cmd *cobra.Command, args []string) error {