Adding a note to `gh search` docs to explain the usage of `--` to exclude certain results #11162

Sukhpreet-s · 2025-06-23T23:45:16Z

This PR improves the gh search docs by explaining the usage of (--) when using GitHub search syntax as query to exclude results based on qualifiers.

Docs for the following gh commands are updated:

gh search code
gh search commit
gh search issues
gh search prs
gh search repos

Looking for feedback / Things to still figure out:

Any improvements in the language used for the note.
While testing the -- behaviour, I found that the -- syntax does not work as expected on Powershell. This might require an addition to the docs notifying this unexpected behaviour to the users.
Command I used to test on Powershell: gh search issues distribution -- repo:rubyforgood/human-essentials -label:stale
Issue: results included issues with the stale label

References used:

https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests

Use a minus (hyphen) symbol to exclude results that match a qualifier. For example, to ignore issues created by the "octocat" user, you'd use -author:octocat in your search. Note that this does not work for missing metadata qualifiers.
https://docs.github.com/en/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax#exclude-results-that-match-a-qualifier

You can narrow down search results by excluding one or more subsets. To exclude all results that are matched by a qualifier, prefix the search qualifier with a hyphen (-).

cli/pkg/cmd/search/prs/prs.go

Lines 34 to 35 in 2b89358

    
           			The command supports constructing queries using the GitHub search syntax, 
        
           			using the parameter and qualifier flags, or a combination of the two.

Sukhpreet-s · 2025-06-24T20:03:22Z

While testing the -- behaviour, I found that the -- syntax does not work as expected on Powershell. This might require an addition to the docs notifying this unexpected behaviour to the users.
Command I used to test on Powershell: gh search issues distribution -- repo:rubyforgood/human-essentials -label:stale
Issue: results included issues with the stale label

To investigate, I spoke with @BagToad, and we found that the request URL is not encoded correctly for certain query patterns.

Note

We used $env:GH_DEBUG = "api" to see detailed output.

❌ Command 1

gh search issues -- distribution repo:rubyforgood/human-essentials -label:stale

URL path:

https://api.github.com/search/issues?page=1&per_page=30&q=distribution+repo%3Arubyforgood%2Fhuman-essentials+-label%3A+stale+type%3Aissue

Problem:
A stray + appears before stale in -label%3A+stale, causing incorrect results (includes issues with the stale label).

❌ Command 2: Full query in quotes

gh search issues -- 'distribution repo:rubyforgood/human-essentials -label:stale'

Request URL:

https://api.github.com/search/issues?page=1&per_page=30&q=distribution+repo%3A%22rubyforgood%2Fhuman-essentials+-label%3Astale%22+type%3Aissue

Problem:
The entire query gets wrapped in quotes, leading to:

Invalid search query "distribution repo:\"rubyforgood/human-essentials -label:stale\" type:issue".

✅ Command 3: Only exclusion part quoted

gh search issues -- distribution repo:rubyforgood/human-essentials '-label:stale'

Request URL:

https://api.github.com/search/issues?page=1&per_page=30&q=distribution+repo%3Arubyforgood%2Fhuman-essentials+-label%3Astale+type%3Aissue

Result:
Works as expected — issues with the stale label are excluded.

Sukhpreet-s · 2025-06-28T18:36:07Z

I noticed that the -- separator works as expected in Windows Command Prompt, but the issue occurs specifically in Windows PowerShell.

For example, the following command:

gh search issues -- distribution repo:rubyforgood/human-essentials -label:stale

runs without problems in cmd.exe, but fails in PowerShell.

BagToad · 2025-07-25T19:25:09Z

The unix stop parse character -- is implemented directly by cobra. So on powershell, you can leverage these with a combination of the powershell stop parse character --% + the -- implemented by cobra:

gh --% search issues --repo rubyforgood/human-essentials -- distribution -label:stale

☝️ the --% allows powershell to ignore everything after it, essentially handing the flag parsing to cobra. The -- then functions the same as we’re used to in a unix shell.

Introduces a new help topic explaining how to use exclusion qualifiers in GitHub search syntax with gh commands, including platform-specific instructions for Unix-like systems and PowerShell. Provides links to relevant documentation for further reference. Co-Authored-By: Sid <41968447+sukhpreet-s@users.noreply.github.com>

BagToad · 2025-07-26T00:07:52Z

@andyfeller I've been working with @Sukhpreet-s on this one. Most of the conversation up till this point has been trying to understand how powershell works in this case. @Sukhpreet-s wanted to make sure we're doing right by powershell users by ensuring our documentation is complete for all platforms.

We decided that the explanation was too meaty to be in each search subcommand and putting this information in the top-level gh search --help only might have discoverability issues. We decided to propose a help topic for this and reference that from each search subcommand ensuring the linkage to the information is discoverable.

Since I've been pretty in the weeds with this and I'm interested in your insight as the original issue author as to where you envisioned this might be documented, I requested your review.

Another thing that came up was potentially moving this documentation to docs.github.com, but we decided to see what a help topic feels like first and get another opinion 🍻

andyfeller · 2025-07-28T19:13:46Z

Thanks for the ping, @BagToad! 🙇

I would suggest having gh help search-syntax content live in gh search long documentation
I wonder if we need something else for those new to working with terminals and shells to understand the various features that gh is designed to support
I would love to discuss ways to expand our help usage logic to allow content to show up in children without duplication

Why I think `gh search` is the place to put this.

I don't think gh help should be commandset-specific as these help topics are cross cutting concerns

Everything else in here is focused on broader topics like accessibility, environment variables, exit codes, JSON exporting, Go template formatting, etc. Things that apply across all gh commands.

Additionally, I support removing gh help actions topic as I'm unsure the value it provides over the Actions command group in gh help:
```
$ gh help
Work seamlessly with GitHub from the command line.

...

GITHUB ACTIONS COMMANDS
  cache:         Manage GitHub Actions caches
  run:           View details about workflow runs
  workflow:      View details about GitHub Actions workflows
```
gh help search-syntax might confuse users looking for documentation on search qualifier documentation

We have links in the respective gh search subcommands for documentation on search syntax.
I don't think help topics are more discoverable than man ... and ... --help going up the commandset

Though I say this because I've ascribed to the Unix philosophy for a while, but I'd say thats the expectation someone who is more comfortable with a terminal or shell would expect.

This PR is already pointing users to run a different command for more information, which could be gh search --help and would be located more closely to the command set than buried under root help topics.

How do we help users understand the terminal and shell behaviors `gh` is designed for?

I struggle with where the GitHub CLI provides broader resources for those new and unfamiliar with terminals and shells because the stop-parse delimiter is a broader topic than just gh search.

From Bash documentation on built-in commands:

Unless otherwise noted, each builtin command documented as accepting options preceded by - accepts -- to signify the end of the options. The :, true, false, and test/[ builtins do not accept options and do not treat -- specially. The exit, logout, return, break, continue, let, and shift builtins accept and process arguments beginning with - without requiring --. Other builtins that accept arguments but are not specified as accepting options interpret arguments beginning with - as invalid options and require -- to prevent this interpretation.

This is only one of several shell expansion features gh is built around that users might be unfamiliar with:

Can we make `--help` generation more manageable?

If there's a concern about managing documentation in multiple places, I'd love to soundboard ideas that could improve the management while allowing that content to appear where people look.

For example, could we enhance the help usage logic below to allow parent commands to define annotations that show up in their children's --help usage?

cli/pkg/cmd/root/help.go

Lines 176 to 194 in 7d70980

    
           	if _, ok := command.Annotations["help:json-fields"]; ok { 
        
           		fields := strings.Split(command.Annotations["help:json-fields"], ",") 
        
           		helpEntries = append(helpEntries, helpEntry{"JSON FIELDS", text.FormatSlice(fields, 80, 0, "", "", true)}) 
        
           	} 
        
           	if _, ok := command.Annotations["help:arguments"]; ok { 
        
           		helpEntries = append(helpEntries, helpEntry{"ARGUMENTS", command.Annotations["help:arguments"]}) 
        
           	} 
        
           	if command.Example != "" { 
        
           		helpEntries = append(helpEntries, helpEntry{"EXAMPLES", command.Example}) 
        
           	} 
        
           	if _, ok := command.Annotations["help:environment"]; ok { 
        
           		helpEntries = append(helpEntries, helpEntry{"ENVIRONMENT VARIABLES", command.Annotations["help:environment"]}) 
        
           	} 
        
           	helpEntries = append(helpEntries, helpEntry{"LEARN MORE", heredoc.Docf(` 
        
           		Use %[1]sgh <command> <subcommand> --help%[1]s for more information about a command. 
        
           		Read the manual at https://cli.github.com/manual 
        
           		Learn about exit codes using %[1]sgh help exit-codes%[1]s 
        
           		Learn about accessibility experiences using %[1]sgh help accessibility%[1]s 
        
           	`, "`")})

BagToad · 2025-07-28T19:49:34Z

👋 @Sukhpreet-s

@andyfeller and I discussed his thoughts a bit more and I wanted to summarize the next steps for this PR:

Move the help topic content to gh search --help.
- Andy and I both agree that this should go in gh search --help's output instead. The content can stay the same.

Do you feel comfortable making those changes? 🙂

Sukhpreet-s · 2025-08-02T07:55:20Z

@andyfeller Thank you for the explanation on the decision to move the note to search --help command 💯

Also, thank you @BagToad for simplifying the next steps ❤️✨

I have pushed the changes. 🚀

BagToad · 2025-08-06T16:24:56Z

pkg/cmd/search/search.go

+		Long:  heredoc.Docf(`
+			Search across all of GitHub.
+
+			Excluding search results that match a qualifier


I wish there was a good way to make this appear more like a heading, but that's not something that should be solved in this PR. Just making a comment about it.

pkg/cmd/search/search.go

BagToad

LGTM - thanks for taking the time with me to work through this one! It definitely turned out to be more complicated. The fact that you both found and helped address the PowerShell difference was great, and no doubt will save someone a bunch of time in the future.

🍻

Sukhpreet-s requested a review from a team as a code owner June 23, 2025 23:45

Sukhpreet-s requested a review from babakks June 23, 2025 23:45

Sukhpreet-s temporarily deployed to cli-automation June 23, 2025 23:45 — with GitHub Actions Inactive

cliAutomation added the external pull request originating outside of the CLI core team label Jun 23, 2025

BagToad self-requested a review July 25, 2025 17:30

BagToad mentioned this pull request Jul 25, 2025

docs: clarify use of '--' delimiter in 'gh search issues' #11313

Closed

docs(search): add note for exclusion search syntax

45876ed

Sukhpreet-s force-pushed the 10480-enhance-gh-search-docs branch from 899d63c to 45876ed Compare July 25, 2025 21:10

BagToad and others added 3 commits July 25, 2025 17:23

docs(search): add reference to gh help search

dd0a0b3

docs(help): rename search-syntax help topic

73f6acc

BagToad requested a review from andyfeller July 26, 2025 00:04

docs(search): move search syntax note to gh search --help

6e400eb

BagToad reviewed Aug 6, 2025

View reviewed changes

Update pkg/cmd/search/search.go

3d9bd69

BagToad approved these changes Aug 6, 2025

View reviewed changes

BagToad added 2 commits August 6, 2025 10:32

Fix linter

4dde087

Merge branch 'trunk' into 10480-enhance-gh-search-docs

b5a6913

BagToad merged commit cf1e14c into cli:trunk Aug 6, 2025
10 of 11 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Adding a note to `gh search` docs to explain the usage of `--` to exclude certain results #11162

Adding a note to `gh search` docs to explain the usage of `--` to exclude certain results #11162

Uh oh!

Sukhpreet-s commented Jun 23, 2025 •

edited

Loading

Uh oh!

Sukhpreet-s commented Jun 24, 2025 •

edited

Loading

Uh oh!

Sukhpreet-s commented Jun 28, 2025

Uh oh!

BagToad commented Jul 25, 2025

Uh oh!

BagToad commented Jul 26, 2025 •

edited

Loading

Uh oh!

andyfeller commented Jul 28, 2025

Uh oh!

BagToad commented Jul 28, 2025 •

edited

Loading

Uh oh!

Sukhpreet-s commented Aug 2, 2025 •

edited

Loading

Uh oh!

BagToad Aug 6, 2025

Uh oh!

Uh oh!

BagToad left a comment

Uh oh!

Uh oh!

Uh oh!

	The command supports constructing queries using the GitHub search syntax,
	using the parameter and qualifier flags, or a combination of the two.

Adding a note to gh search docs to explain the usage of -- to exclude certain results #11162

Adding a note to gh search docs to explain the usage of -- to exclude certain results #11162

Uh oh!

Conversation

Sukhpreet-s commented Jun 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Looking for feedback / Things to still figure out:

References used:

Uh oh!

Sukhpreet-s commented Jun 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

❌ Command 1

❌ Command 2: Full query in quotes

✅ Command 3: Only exclusion part quoted

Uh oh!

Sukhpreet-s commented Jun 28, 2025

Uh oh!

BagToad commented Jul 25, 2025

Uh oh!

BagToad commented Jul 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

andyfeller commented Jul 28, 2025

Why I think gh search is the place to put this.

How do we help users understand the terminal and shell behaviors gh is designed for?

Can we make --help generation more manageable?

Uh oh!

BagToad commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Sukhpreet-s commented Aug 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

BagToad Aug 6, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

BagToad left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Adding a note to `gh search` docs to explain the usage of `--` to exclude certain results #11162

Adding a note to `gh search` docs to explain the usage of `--` to exclude certain results #11162

Sukhpreet-s commented Jun 23, 2025 •

edited

Loading

Sukhpreet-s commented Jun 24, 2025 •

edited

Loading

BagToad commented Jul 26, 2025 •

edited

Loading

Why I think `gh search` is the place to put this.

How do we help users understand the terminal and shell behaviors `gh` is designed for?

Can we make `--help` generation more manageable?

BagToad commented Jul 28, 2025 •

edited

Loading

Sukhpreet-s commented Aug 2, 2025 •

edited

Loading