Help users learn to quote arguments with spaces in their shell

[mislav]

Running this in a shell such as bash or zsh will not produce the sometimes-expected result of looking up issues under the help wanted label:

# doesn't work:
gh issue list -l help wanted

This is because the value help wanted should be quoted or escaped in one's shell to ensure that it's passed as a single value to --label, rather than as two distinct arguments help + wanted (where the latter wouldn't be interpreted as relating to --label at all):

# works:
gh issue list -l "help wanted"

# also works:
gh issue list -l help\ wanted

This isn't a bug with CLI, but is a common pitfall for shell-users in general that we could ideally help our users detect and recover from. Possible approaches:

• Include example of passing labels with spaces in gh help issue list docs
• Detect extra, unaccounted arguments to gh issue list ("wanted" in the above example) and present an error such as “unrecognized argument 'wanted': did you forget to quote values with spaces?”

Originally reported by @tierninho

Loosely related issues that stem as consequence of shell behavior (as opposed to being bugs in gh): #223 #595 #315

[ShubhankarKG]

HI there, @mislav and the team. I've been using cli for a while now, and it feels amazing to be honest. Kudos to the team.!.

I'd like to take this one up. Incrementing the already mentioned solutions, here is how I'd like to proceed with the same.

In command/issue.go :

1. A change here.

func listHeader(arguments) string {
...
if (hasFilters) {
return fmt.Sprintf("No %ss match your search in %s. Perhaps you forgot to escape the spaces ? ", itemName, repoName)
   }
...
}

2. A change in the docs so:

var issueListCmd = &cobra.Command{
	Use:   "list",
	Short: "List and filter issues in this repository",
        Long: `This commands lets you list issues according to the labels that you have passed
Remember to escape whitespaces or mention the whitespace separated issue names within quotations in your terminal to help identify cli the correctly named issue.
Usage Example:-
gh issue list -l help\ wanted
gh issue list -l "help wanted"
`
	RunE:  issueList,
}

Any more things that need to be added ? Please let me know. Thanks.

[mislav]

Yay, thanks for offering to help!

1. I think that issue list -l help wanted should abort the command in the arguments processing stage because wanted will appear as an extra argument in the end. You could try to detect that by adding a issueListCmd.Args handler, for example: issueListCmd.Args = cobra.NoArgs. This would result in Cobra printing unknown command "wanted" for "gh issue list" for the faulty invocation, which is a little bit better than the current behavior, but the error message might still be a tiny bit confusing. You could maybe see if there is a way to make it clearer?

2. Including an example sounds like a good idea! Please place examples in issueListCmd.Example field rather than in issueListCmd.Long. Also, let's only include the double-quote example and not the backslash-escape one; the latter works but I find it hard to parse for a human.

[ShubhankarKG]

1. You could maybe see if there is a way to make it clearer?

It seems to me that we can have a custom validator that provides the error message that we need to give. What I mean is-

var issueListCmd = &cobra.Command{
	---
	Args: func (cmd *cobra.Command, args []string) error {
	if len(args) > 0 {
		return fmt.Errorf("unknown command %q for %q. Please include quotes if necessary", args[0], cmd.CommandPath())
	}
	return nil
   }
	---
}

We can just write what we need. So that should be a bit easy now.

2. Please place examples in issueListCmd.Example field rather than in issueListCmd.Long. Also, let's only include the double-quote example and not the backslash-escape one; the latter works but I find it hard to parse for a human.

Sure thing. Can update as needed.

[mislav]

Looking forward to the pull request! ✨