From 5314e7c39804cbc0462cff96ee293d55f6a8e7c6 Mon Sep 17 00:00:00 2001 From: chemotaxis Date: Mon, 19 Jul 2021 00:36:07 -0400 Subject: [PATCH 1/5] Add note about double quotes on non-Unix-like shells On non-Unix-like shells like Windows Command Prompt, single quotes are handled differently. You need to define aliases using double quotes instead of single quotes. I added an inline example to illustrate the quotes. The example is formatted as inline code blocks in Markdown. Unfortunately, because Go uses backticks for raw string literals, I needed to do some rather ugly string concatenation in order to get the backticks included in the doc string. This also rearranges the notes so that the platform specific notes are at the end of the documentation. --- pkg/cmd/alias/set/set.go | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/pkg/cmd/alias/set/set.go b/pkg/cmd/alias/set/set.go index 8a452cca5..83d07b229 100644 --- a/pkg/cmd/alias/set/set.go +++ b/pkg/cmd/alias/set/set.go @@ -47,17 +47,24 @@ func NewCmdSet(f *cmdutil.Factory, runF func(*SetOptions) error) *cobra.Command 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. - Platform note: on Windows, shell aliases are executed via "sh" as installed by Git For Windows. If - you have installed git on Windows in some other way, shell aliases may not work for you. - 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:** + + - Shell aliases are executed via 'sh' as installed by Git For Windows. + If you have installed git in some other way, shell aliases may not work for you. + - If you are using a shell that is *not* Unix-like (e.g. Command Prompt, cmd.exe), + make sure to *double quote* when defining an alias. + For instance, use ` + "`gh alias set pv \"pr view\"`" + ` instead of ` + "`gh alias set pv 'pr view'`. " + + ` + All the examples assume a Unix-like shell. `), Example: heredoc.Doc(` $ gh alias set pv 'pr view' $ gh pv -w 123 #=> gh pr view -w 123 - + $ gh alias set bugs 'issue list --label="bugs"' $ gh bugs From 23ffca45f7dd7042239e7b89f5907a5f1883324d Mon Sep 17 00:00:00 2001 From: chemotaxis Date: Mon, 19 Jul 2021 00:46:06 -0400 Subject: [PATCH 2/5] Unify use of single quotes to mark shell arguments and variables The first paragraph uses single quotes when referring to shell arguments and variables, but the rest of the docs use double quotes. This commit switches to using single quotes throughout the docs. I prefer to use single quotes inside string literals because Go uses double quotes to define a string literal. --- pkg/cmd/alias/set/set.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pkg/cmd/alias/set/set.go b/pkg/cmd/alias/set/set.go index 83d07b229..bbc7480f2 100644 --- a/pkg/cmd/alias/set/set.go +++ b/pkg/cmd/alias/set/set.go @@ -43,9 +43,9 @@ func NewCmdSet(f *cmdutil.Factory, runF func(*SetOptions) error) *cobra.Command for commands with mixed quotes or multiple lines. 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 + 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. + arguments, you must explicitly accept them using '$1', '$2', etc., or '$@' to accept all of them. 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'. From 2c52819c1a158f494f2e258e159a56d82ceab85c Mon Sep 17 00:00:00 2001 From: chemotaxis Date: Mon, 19 Jul 2021 15:28:25 -0400 Subject: [PATCH 3/5] Remove note about using Git for Windows As discussed in pull request #4013. --- pkg/cmd/alias/set/set.go | 2 -- 1 file changed, 2 deletions(-) diff --git a/pkg/cmd/alias/set/set.go b/pkg/cmd/alias/set/set.go index bbc7480f2..5333046ba 100644 --- a/pkg/cmd/alias/set/set.go +++ b/pkg/cmd/alias/set/set.go @@ -52,8 +52,6 @@ func NewCmdSet(f *cmdutil.Factory, runF func(*SetOptions) error) *cobra.Command **Platform notes for Windows:** - - Shell aliases are executed via 'sh' as installed by Git For Windows. - If you have installed git in some other way, shell aliases may not work for you. - If you are using a shell that is *not* Unix-like (e.g. Command Prompt, cmd.exe), make sure to *double quote* when defining an alias. For instance, use ` + "`gh alias set pv \"pr view\"`" + ` instead of ` + "`gh alias set pv 'pr view'`. " + From 1e4e536bcbdeab4c733db2462c6840ddc06e88c9 Mon Sep 17 00:00:00 2001 From: chemotaxis Date: Mon, 19 Jul 2021 15:44:37 -0400 Subject: [PATCH 4/5] Revise Windows note --- pkg/cmd/alias/set/set.go | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/pkg/cmd/alias/set/set.go b/pkg/cmd/alias/set/set.go index 5333046ba..1bc732742 100644 --- a/pkg/cmd/alias/set/set.go +++ b/pkg/cmd/alias/set/set.go @@ -50,14 +50,10 @@ func NewCmdSet(f *cmdutil.Factory, runF func(*SetOptions) error) *cobra.Command 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:** + Platform notes for Windows: - - If you are using a shell that is *not* Unix-like (e.g. Command Prompt, cmd.exe), - make sure to *double quote* when defining an alias. - For instance, use ` + "`gh alias set pv \"pr view\"`" + ` instead of ` + "`gh alias set pv 'pr view'`. " + - ` - All the examples assume a Unix-like shell. - `), + - 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'`. "), Example: heredoc.Doc(` $ gh alias set pv 'pr view' $ gh pv -w 123 From efa4d43cf4c800fb4646046f8410837505c5119e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mislav=20Marohni=C4=87?= Date: Tue, 20 Jul 2021 15:32:51 +0200 Subject: [PATCH 5/5] 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 ", 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 {