From 45876eddc290075e4ad148b5028f26b6472b09de Mon Sep 17 00:00:00 2001 From: Sukh Date: Mon, 23 Jun 2025 13:19:37 -0400 Subject: [PATCH 1/7] docs(search): add note for exclusion search syntax --- pkg/cmd/search/code/code.go | 3 +++ pkg/cmd/search/commits/commits.go | 3 +++ pkg/cmd/search/issues/issues.go | 3 +++ pkg/cmd/search/prs/prs.go | 3 +++ pkg/cmd/search/repos/repos.go | 3 +++ 5 files changed, 15 insertions(+) diff --git a/pkg/cmd/search/code/code.go b/pkg/cmd/search/code/code.go index d03526c4d9e..3a439e5cd7b 100644 --- a/pkg/cmd/search/code/code.go +++ b/pkg/cmd/search/code/code.go @@ -46,6 +46,9 @@ func NewCmdCode(f *cmdutil.Factory, runF func(*CodeOptions) error) *cobra.Comman Note that these search results are powered by what is now a legacy GitHub code search engine. The results might not match what is seen on %[1]sgithub.com%[1]s, and new features like regex search are not yet available via the GitHub API. + + Note: When using GitHub search syntax to exclude results (e.g. '-language:xml'), you must use + a '--' delimiter before the search query to separate it from command flags. `, "`"), Example: heredoc.Doc(` # Search code matching "react" and "lifecycle" diff --git a/pkg/cmd/search/commits/commits.go b/pkg/cmd/search/commits/commits.go index fb1742dc9da..161ecc6a93c 100644 --- a/pkg/cmd/search/commits/commits.go +++ b/pkg/cmd/search/commits/commits.go @@ -45,6 +45,9 @@ func NewCmdCommits(f *cmdutil.Factory, runF func(*CommitsOptions) error) *cobra. GitHub search syntax is documented at: + + Note: When using GitHub search syntax to exclude results (e.g. '-user:monalisa'), you must use + a '--' delimiter before the search query to separate it from command flags. `), Example: heredoc.Doc(` # Search commits matching set of keywords "readme" and "typo" diff --git a/pkg/cmd/search/issues/issues.go b/pkg/cmd/search/issues/issues.go index e1f4105aea4..af6e9d64c83 100644 --- a/pkg/cmd/search/issues/issues.go +++ b/pkg/cmd/search/issues/issues.go @@ -34,6 +34,9 @@ func NewCmdIssues(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *c GitHub search syntax is documented at: + + Note: When using GitHub search syntax to exclude results (e.g. '-label:bug'), you must use + a '--' delimiter before the search query to separate it from command flags. `), Example: heredoc.Doc(` # Search issues matching set of keywords "readme" and "typo" diff --git a/pkg/cmd/search/prs/prs.go b/pkg/cmd/search/prs/prs.go index f7a96c5bf01..b268ea3e5ce 100644 --- a/pkg/cmd/search/prs/prs.go +++ b/pkg/cmd/search/prs/prs.go @@ -36,6 +36,9 @@ func NewCmdPrs(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *cobr GitHub search syntax is documented at: + + Note: When using GitHub search syntax to exclude results (e.g. '-label:bug'), you must use + a '--' delimiter before the search query to separate it from command flags. `), Example: heredoc.Doc(` # Search pull requests matching set of keywords "fix" and "bug" diff --git a/pkg/cmd/search/repos/repos.go b/pkg/cmd/search/repos/repos.go index 2815ee6dc2b..733d7b7c467 100644 --- a/pkg/cmd/search/repos/repos.go +++ b/pkg/cmd/search/repos/repos.go @@ -46,6 +46,9 @@ func NewCmdRepos(f *cmdutil.Factory, runF func(*ReposOptions) error) *cobra.Comm GitHub search syntax is documented at: + + Note: When using GitHub search syntax to exclude results (e.g. '-topic:linux'), you must use + a '--' delimiter before the search query to separate it from command flags. `), Example: heredoc.Doc(` # Search repositories matching set of keywords "cli" and "shell" From 254119e49880b1dbc6ca2c0fa66c5a6a6d8d346a Mon Sep 17 00:00:00 2001 From: Kynan Ware <47394200+BagToad@users.noreply.github.com> Date: Fri, 25 Jul 2025 17:23:45 -0600 Subject: [PATCH 2/7] Add help topic for search syntax in gh commands 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> --- pkg/cmd/root/help_topic.go | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/pkg/cmd/root/help_topic.go b/pkg/cmd/root/help_topic.go index a375d9e2050..6ea626e0673 100644 --- a/pkg/cmd/root/help_topic.go +++ b/pkg/cmd/root/help_topic.go @@ -304,6 +304,35 @@ var HelpTopics = []helpTopic{ control some behavior. `), }, + { + name: "search", + short: "Search syntax for gh commands", + long: heredoc.Docf(` + Excluding search results that match a qualifier + + In a browser, the GitHub search syntax supports excluding results that match a search qualifier + by prefixing the qualifier with a hyphen. For example, to search for issues that + do not have the label "bug", you would use %[1]s-label:bug%[1]s as a search qualifier. + + %[1]sgh%[1]s supports this syntax in %[1]sgh search%[1]s as well, but it requires extra + syntax to avoid the hyphen being interpreted as a command line flag because it begins with a hyphen. + + On Unix-like systems, you can use the %[1]s--%[1]s argument to indicate that + the arguments that follow are not a flag, but rather a query string. For example: + + $ gh search issues -- "my-search-query -label:bug" + + On PowerShell, you must use both the %[1]s--%[2]s%[1]s argument and the %[1]s--%[1]s argument to + produce the same effect. For example: + + $ gh --%[2]s search issues -- "my search query -label:bug" + + See the following for more information: + - GitHub search syntax: + - The PowerShell stop parse flag %[1]s--%[2]s%[1]s: + - The Unix-like %[1]s--%[1]s argument: + `, "`", "%"), + }, } func NewCmdHelpTopic(ios *iostreams.IOStreams, ht helpTopic) *cobra.Command { From dd0a0b3045fde60f8fd2bec7c0b1435173b80fa1 Mon Sep 17 00:00:00 2001 From: Sukh Date: Fri, 25 Jul 2025 19:49:59 -0400 Subject: [PATCH 3/7] docs(search): add reference to `gh help search` --- pkg/cmd/search/code/code.go | 3 +-- pkg/cmd/search/commits/commits.go | 7 +++---- pkg/cmd/search/issues/issues.go | 7 +++---- pkg/cmd/search/prs/prs.go | 7 +++---- pkg/cmd/search/repos/repos.go | 7 +++---- 5 files changed, 13 insertions(+), 18 deletions(-) diff --git a/pkg/cmd/search/code/code.go b/pkg/cmd/search/code/code.go index 3a439e5cd7b..5e80c1017f2 100644 --- a/pkg/cmd/search/code/code.go +++ b/pkg/cmd/search/code/code.go @@ -47,8 +47,7 @@ func NewCmdCode(f *cmdutil.Factory, runF func(*CodeOptions) error) *cobra.Comman The results might not match what is seen on %[1]sgithub.com%[1]s, and new features like regex search are not yet available via the GitHub API. - Note: When using GitHub search syntax to exclude results (e.g. '-language:xml'), you must use - a '--' delimiter before the search query to separate it from command flags. + For more information on handling search queries containing a hyphen, run %[1]sgh help search-syntax%[1]s. `, "`"), Example: heredoc.Doc(` # Search code matching "react" and "lifecycle" diff --git a/pkg/cmd/search/commits/commits.go b/pkg/cmd/search/commits/commits.go index 161ecc6a93c..ed5d1f758cb 100644 --- a/pkg/cmd/search/commits/commits.go +++ b/pkg/cmd/search/commits/commits.go @@ -37,7 +37,7 @@ func NewCmdCommits(f *cmdutil.Factory, runF func(*CommitsOptions) error) *cobra. cmd := &cobra.Command{ Use: "commits []", Short: "Search for commits", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Search for commits on GitHub. The command supports constructing queries using the GitHub search syntax, @@ -46,9 +46,8 @@ func NewCmdCommits(f *cmdutil.Factory, runF func(*CommitsOptions) error) *cobra. GitHub search syntax is documented at: - Note: When using GitHub search syntax to exclude results (e.g. '-user:monalisa'), you must use - a '--' delimiter before the search query to separate it from command flags. - `), + For more information on handling search queries containing a hyphen, run %[1]sgh help search-syntax%[1]s. + `, "`"), Example: heredoc.Doc(` # Search commits matching set of keywords "readme" and "typo" $ gh search commits readme typo diff --git a/pkg/cmd/search/issues/issues.go b/pkg/cmd/search/issues/issues.go index af6e9d64c83..0edca4b31f5 100644 --- a/pkg/cmd/search/issues/issues.go +++ b/pkg/cmd/search/issues/issues.go @@ -26,7 +26,7 @@ func NewCmdIssues(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *c cmd := &cobra.Command{ Use: "issues []", Short: "Search for issues", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Search for issues on GitHub. The command supports constructing queries using the GitHub search syntax, @@ -35,9 +35,8 @@ func NewCmdIssues(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *c GitHub search syntax is documented at: - Note: When using GitHub search syntax to exclude results (e.g. '-label:bug'), you must use - a '--' delimiter before the search query to separate it from command flags. - `), + For more information on handling search queries containing a hyphen, run %[1]sgh help search-syntax%[1]s. + `, "`"), Example: heredoc.Doc(` # Search issues matching set of keywords "readme" and "typo" $ gh search issues readme typo diff --git a/pkg/cmd/search/prs/prs.go b/pkg/cmd/search/prs/prs.go index b268ea3e5ce..39203f5fbc8 100644 --- a/pkg/cmd/search/prs/prs.go +++ b/pkg/cmd/search/prs/prs.go @@ -28,7 +28,7 @@ func NewCmdPrs(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *cobr cmd := &cobra.Command{ Use: "prs []", Short: "Search for pull requests", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Search for pull requests on GitHub. The command supports constructing queries using the GitHub search syntax, @@ -37,9 +37,8 @@ func NewCmdPrs(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *cobr GitHub search syntax is documented at: - Note: When using GitHub search syntax to exclude results (e.g. '-label:bug'), you must use - a '--' delimiter before the search query to separate it from command flags. - `), + For more information on handling search queries containing a hyphen, run %[1]sgh help search-syntax%[1]s. + `, "`"), Example: heredoc.Doc(` # Search pull requests matching set of keywords "fix" and "bug" $ gh search prs fix bug diff --git a/pkg/cmd/search/repos/repos.go b/pkg/cmd/search/repos/repos.go index 733d7b7c467..a7116dd5885 100644 --- a/pkg/cmd/search/repos/repos.go +++ b/pkg/cmd/search/repos/repos.go @@ -38,7 +38,7 @@ func NewCmdRepos(f *cmdutil.Factory, runF func(*ReposOptions) error) *cobra.Comm cmd := &cobra.Command{ Use: "repos []", Short: "Search for repositories", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Search for repositories on GitHub. The command supports constructing queries using the GitHub search syntax, @@ -47,9 +47,8 @@ func NewCmdRepos(f *cmdutil.Factory, runF func(*ReposOptions) error) *cobra.Comm GitHub search syntax is documented at: - Note: When using GitHub search syntax to exclude results (e.g. '-topic:linux'), you must use - a '--' delimiter before the search query to separate it from command flags. - `), + For more information on handling search queries containing a hyphen, run %[1]sgh help search-syntax%[1]s. + `, "`"), Example: heredoc.Doc(` # Search repositories matching set of keywords "cli" and "shell" $ gh search repos cli shell From 73f6acc709e18d823fcb91df73de3932e75792f7 Mon Sep 17 00:00:00 2001 From: Sukh Date: Fri, 25 Jul 2025 19:56:39 -0400 Subject: [PATCH 4/7] docs(help): rename `search-syntax` help topic --- pkg/cmd/root/help_topic.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg/cmd/root/help_topic.go b/pkg/cmd/root/help_topic.go index 6ea626e0673..322bc4f775c 100644 --- a/pkg/cmd/root/help_topic.go +++ b/pkg/cmd/root/help_topic.go @@ -305,7 +305,7 @@ var HelpTopics = []helpTopic{ `), }, { - name: "search", + name: "search-syntax", short: "Search syntax for gh commands", long: heredoc.Docf(` Excluding search results that match a qualifier From 6e400eb4a19e77f9d810ca73f679cac37c56df36 Mon Sep 17 00:00:00 2001 From: Sukh Date: Sat, 2 Aug 2025 03:01:40 -0400 Subject: [PATCH 5/7] docs(search): move search syntax note to `gh search --help` --- pkg/cmd/root/help_topic.go | 29 ----------------------------- pkg/cmd/search/code/code.go | 2 +- pkg/cmd/search/commits/commits.go | 2 +- pkg/cmd/search/issues/issues.go | 2 +- pkg/cmd/search/prs/prs.go | 2 +- pkg/cmd/search/repos/repos.go | 2 +- pkg/cmd/search/search.go | 29 ++++++++++++++++++++++++++++- 7 files changed, 33 insertions(+), 35 deletions(-) diff --git a/pkg/cmd/root/help_topic.go b/pkg/cmd/root/help_topic.go index 322bc4f775c..a375d9e2050 100644 --- a/pkg/cmd/root/help_topic.go +++ b/pkg/cmd/root/help_topic.go @@ -304,35 +304,6 @@ var HelpTopics = []helpTopic{ control some behavior. `), }, - { - name: "search-syntax", - short: "Search syntax for gh commands", - long: heredoc.Docf(` - Excluding search results that match a qualifier - - In a browser, the GitHub search syntax supports excluding results that match a search qualifier - by prefixing the qualifier with a hyphen. For example, to search for issues that - do not have the label "bug", you would use %[1]s-label:bug%[1]s as a search qualifier. - - %[1]sgh%[1]s supports this syntax in %[1]sgh search%[1]s as well, but it requires extra - syntax to avoid the hyphen being interpreted as a command line flag because it begins with a hyphen. - - On Unix-like systems, you can use the %[1]s--%[1]s argument to indicate that - the arguments that follow are not a flag, but rather a query string. For example: - - $ gh search issues -- "my-search-query -label:bug" - - On PowerShell, you must use both the %[1]s--%[2]s%[1]s argument and the %[1]s--%[1]s argument to - produce the same effect. For example: - - $ gh --%[2]s search issues -- "my search query -label:bug" - - See the following for more information: - - GitHub search syntax: - - The PowerShell stop parse flag %[1]s--%[2]s%[1]s: - - The Unix-like %[1]s--%[1]s argument: - `, "`", "%"), - }, } func NewCmdHelpTopic(ios *iostreams.IOStreams, ht helpTopic) *cobra.Command { diff --git a/pkg/cmd/search/code/code.go b/pkg/cmd/search/code/code.go index 5e80c1017f2..7ef2a4193f0 100644 --- a/pkg/cmd/search/code/code.go +++ b/pkg/cmd/search/code/code.go @@ -47,7 +47,7 @@ func NewCmdCode(f *cmdutil.Factory, runF func(*CodeOptions) error) *cobra.Comman The results might not match what is seen on %[1]sgithub.com%[1]s, and new features like regex search are not yet available via the GitHub API. - For more information on handling search queries containing a hyphen, run %[1]sgh help search-syntax%[1]s. + For more information on handling search queries containing a hyphen, run %[1]sgh search --help%[1]s. `, "`"), Example: heredoc.Doc(` # Search code matching "react" and "lifecycle" diff --git a/pkg/cmd/search/commits/commits.go b/pkg/cmd/search/commits/commits.go index ed5d1f758cb..939109b65de 100644 --- a/pkg/cmd/search/commits/commits.go +++ b/pkg/cmd/search/commits/commits.go @@ -46,7 +46,7 @@ func NewCmdCommits(f *cmdutil.Factory, runF func(*CommitsOptions) error) *cobra. GitHub search syntax is documented at: - For more information on handling search queries containing a hyphen, run %[1]sgh help search-syntax%[1]s. + For more information on handling search queries containing a hyphen, run %[1]sgh search --help%[1]s. `, "`"), Example: heredoc.Doc(` # Search commits matching set of keywords "readme" and "typo" diff --git a/pkg/cmd/search/issues/issues.go b/pkg/cmd/search/issues/issues.go index 0edca4b31f5..1d6ec6428c3 100644 --- a/pkg/cmd/search/issues/issues.go +++ b/pkg/cmd/search/issues/issues.go @@ -35,7 +35,7 @@ func NewCmdIssues(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *c GitHub search syntax is documented at: - For more information on handling search queries containing a hyphen, run %[1]sgh help search-syntax%[1]s. + For more information on handling search queries containing a hyphen, run %[1]sgh search --help%[1]s. `, "`"), Example: heredoc.Doc(` # Search issues matching set of keywords "readme" and "typo" diff --git a/pkg/cmd/search/prs/prs.go b/pkg/cmd/search/prs/prs.go index 39203f5fbc8..98ab730b595 100644 --- a/pkg/cmd/search/prs/prs.go +++ b/pkg/cmd/search/prs/prs.go @@ -37,7 +37,7 @@ func NewCmdPrs(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *cobr GitHub search syntax is documented at: - For more information on handling search queries containing a hyphen, run %[1]sgh help search-syntax%[1]s. + For more information on handling search queries containing a hyphen, run %[1]sgh search --help%[1]s. `, "`"), Example: heredoc.Doc(` # Search pull requests matching set of keywords "fix" and "bug" diff --git a/pkg/cmd/search/repos/repos.go b/pkg/cmd/search/repos/repos.go index a7116dd5885..0a4275a87ca 100644 --- a/pkg/cmd/search/repos/repos.go +++ b/pkg/cmd/search/repos/repos.go @@ -47,7 +47,7 @@ func NewCmdRepos(f *cmdutil.Factory, runF func(*ReposOptions) error) *cobra.Comm GitHub search syntax is documented at: - For more information on handling search queries containing a hyphen, run %[1]sgh help search-syntax%[1]s. + For more information on handling search queries containing a hyphen, run %[1]sgh search --help%[1]s. `, "`"), Example: heredoc.Doc(` # Search repositories matching set of keywords "cli" and "shell" diff --git a/pkg/cmd/search/search.go b/pkg/cmd/search/search.go index e8714065bab..e79e1ec4c36 100644 --- a/pkg/cmd/search/search.go +++ b/pkg/cmd/search/search.go @@ -3,6 +3,7 @@ package search import ( "github.com/cli/cli/v2/pkg/cmdutil" "github.com/spf13/cobra" + "github.com/MakeNowJust/heredoc" searchCodeCmd "github.com/cli/cli/v2/pkg/cmd/search/code" searchCommitsCmd "github.com/cli/cli/v2/pkg/cmd/search/commits" @@ -15,7 +16,33 @@ func NewCmdSearch(f *cmdutil.Factory) *cobra.Command { cmd := &cobra.Command{ Use: "search ", Short: "Search for repositories, issues, and pull requests", - Long: "Search across all of GitHub.", + Long: heredoc.Docf(` + Search across all of GitHub. + + Excluding search results that match a qualifier + + In a browser, the GitHub search syntax supports excluding results that match a search qualifier + by prefixing the qualifier with a hyphen. For example, to search for issues that + do not have the label "bug", you would use %[1]s-label:bug%[1]s as a search qualifier. + + %[1]sgh%[1]s supports this syntax in %[1]sgh search%[1]s as well, but it requires extra + syntax to avoid the hyphen being interpreted as a command line flag because it begins with a hyphen. + + On Unix-like systems, you can use the %[1]s--%[1]s argument to indicate that + the arguments that follow are not a flag, but rather a query string. For example: + + $ gh search issues -- "my-search-query -label:bug" + + On PowerShell, you must use both the %[1]s--%[2]s%[1]s argument and the %[1]s--%[1]s argument to + produce the same effect. For example: + + $ gh --%[2]s search issues -- "my search query -label:bug" + + See the following for more information: + - GitHub search syntax: + - The PowerShell stop parse flag %[1]s--%[2]s%[1]s: + - The Unix-like %[1]s--%[1]s argument: + `, "`", "%"), } cmd.AddCommand(searchCodeCmd.NewCmdCode(f, nil)) From 3d9bd69e11a5fc338ef9c84ff7caea3cf5193cb4 Mon Sep 17 00:00:00 2001 From: Kynan Ware <47394200+BagToad@users.noreply.github.com> Date: Wed, 6 Aug 2025 10:28:56 -0600 Subject: [PATCH 6/7] Update pkg/cmd/search/search.go --- pkg/cmd/search/search.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg/cmd/search/search.go b/pkg/cmd/search/search.go index e79e1ec4c36..551faf1f279 100644 --- a/pkg/cmd/search/search.go +++ b/pkg/cmd/search/search.go @@ -26,7 +26,7 @@ func NewCmdSearch(f *cmdutil.Factory) *cobra.Command { do not have the label "bug", you would use %[1]s-label:bug%[1]s as a search qualifier. %[1]sgh%[1]s supports this syntax in %[1]sgh search%[1]s as well, but it requires extra - syntax to avoid the hyphen being interpreted as a command line flag because it begins with a hyphen. + command line arguments to avoid the hyphen being interpreted as a command line flag because it begins with a hyphen. On Unix-like systems, you can use the %[1]s--%[1]s argument to indicate that the arguments that follow are not a flag, but rather a query string. For example: From 4dde0871bd6cd5207e54fa6c9183d5d52f53e81e Mon Sep 17 00:00:00 2001 From: Kynan Ware <47394200+BagToad@users.noreply.github.com> Date: Wed, 6 Aug 2025 10:32:46 -0600 Subject: [PATCH 7/7] Fix linter --- pkg/cmd/search/search.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pkg/cmd/search/search.go b/pkg/cmd/search/search.go index 551faf1f279..2f435f14dd5 100644 --- a/pkg/cmd/search/search.go +++ b/pkg/cmd/search/search.go @@ -1,9 +1,9 @@ package search import ( + "github.com/MakeNowJust/heredoc" "github.com/cli/cli/v2/pkg/cmdutil" "github.com/spf13/cobra" - "github.com/MakeNowJust/heredoc" searchCodeCmd "github.com/cli/cli/v2/pkg/cmd/search/code" searchCommitsCmd "github.com/cli/cli/v2/pkg/cmd/search/commits" @@ -16,7 +16,7 @@ func NewCmdSearch(f *cmdutil.Factory) *cobra.Command { cmd := &cobra.Command{ Use: "search ", Short: "Search for repositories, issues, and pull requests", - Long: heredoc.Docf(` + Long: heredoc.Docf(` Search across all of GitHub. Excluding search results that match a qualifier