diff --git a/pkg/cmd/search/code/code.go b/pkg/cmd/search/code/code.go index d03526c4d9e..7ef2a4193f0 100644 --- a/pkg/cmd/search/code/code.go +++ b/pkg/cmd/search/code/code.go @@ -46,6 +46,8 @@ 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. + + 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 fb1742dc9da..939109b65de 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, @@ -45,7 +45,9 @@ 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 search --help%[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 e1f4105aea4..1d6ec6428c3 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, @@ -34,7 +34,9 @@ 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 search --help%[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 f7a96c5bf01..98ab730b595 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, @@ -36,7 +36,9 @@ 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 search --help%[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 2815ee6dc2b..0a4275a87ca 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, @@ -46,7 +46,9 @@ 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 search --help%[1]s. + `, "`"), Example: heredoc.Doc(` # Search repositories matching set of keywords "cli" and "shell" $ gh search repos cli shell diff --git a/pkg/cmd/search/search.go b/pkg/cmd/search/search.go index e8714065bab..2f435f14dd5 100644 --- a/pkg/cmd/search/search.go +++ b/pkg/cmd/search/search.go @@ -1,6 +1,7 @@ package search import ( + "github.com/MakeNowJust/heredoc" "github.com/cli/cli/v2/pkg/cmdutil" "github.com/spf13/cobra" @@ -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 + 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: + + $ 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))