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] 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 a375d9e20..6ea626e06 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: <https://docs.github.com/en/search-github/getting-started-with-searching-on-github/understanding-the-search-syntax#exclude-results-that-match-a-qualifier>
+			- The PowerShell stop parse flag %[1]s--%[2]s%[1]s: <https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.5#the-stop-parsing-token>
+			- The Unix-like %[1]s--%[1]s argument: <https://www.gnu.org/software/bash/manual/bash.html#Shell-Builtin-Commands-1>
+		`, "`", "%"),
+	},
 }
 
 func NewCmdHelpTopic(ios *iostreams.IOStreams, ht helpTopic) *cobra.Command {