Skip to content

Commit 286ba5e

Browse files
mislavmislav
committed
issue/pr list: clarify search syntax
1 parent 5f8bdd6 commit 286ba5e

File tree

2 files changed

+26
-18
lines changed

2 files changed

+26
-18
lines changed

‎pkg/cmd/issue/list/list.go‎

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -57,12 +57,17 @@ func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Comman
5757

5858
cmd := &cobra.Command{
5959
Use: "list",
60-
Short: "List and filter issues in this repository",
60+
Short: "List issues in a repository",
61+
Long: heredoc.Doc(`
62+
List issues in a GitHub repository.
63+
64+
The search query syntax is documented here:
65+
<https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests>
66+
`),
6167
Example: heredoc.Doc(`
62-
$ gh issue list -l "bug" -l "help wanted"
63-
$ gh issue list -A monalisa
64-
$ gh issue list -a "@me"
65-
$ gh issue list --web
68+
$ gh issue list --label "bug" --label "help wanted"
69+
$ gh issue list --author monalisa
70+
$ gh issue list --assignee "@me"
6671
$ gh issue list --milestone "The big 1.0"
6772
$ gh issue list --search "error no:assignee sort:created-asc"
6873
`),
@@ -83,17 +88,17 @@ func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Comman
8388
},
8489
}
8590

86-
cmd.Flags().BoolVarP(&opts.WebMode, "web", "w", false, "Open the browser to list the issue(s)")
91+
cmd.Flags().BoolVarP(&opts.WebMode, "web", "w", false, "List issues in the web browser")
8792
cmd.Flags().StringVarP(&opts.Assignee, "assignee", "a", "", "Filter by assignee")
88-
cmd.Flags().StringSliceVarP(&opts.Labels, "label", "l", nil, "Filter by labels")
93+
cmd.Flags().StringSliceVarP(&opts.Labels, "label", "l", nil, "Filter by label")
8994
cmd.Flags().StringVarP(&opts.State, "state", "s", "open", "Filter by state: {open|closed|all}")
9095
_ = cmd.RegisterFlagCompletionFunc("state", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
9196
return []string{"open", "closed", "all"}, cobra.ShellCompDirectiveNoFileComp
9297
})
9398
cmd.Flags().IntVarP(&opts.LimitResults, "limit", "L", 30, "Maximum number of issues to fetch")
9499
cmd.Flags().StringVarP(&opts.Author, "author", "A", "", "Filter by author")
95100
cmd.Flags().StringVar(&opts.Mention, "mention", "", "Filter by mention")
96-
cmd.Flags().StringVarP(&opts.Milestone, "milestone", "m", "", "Filter by milestone `number` or `title`")
101+
cmd.Flags().StringVarP(&opts.Milestone, "milestone", "m", "", "Filter by milestone number or title")
97102
cmd.Flags().StringVarP(&opts.Search, "search", "S", "", "Search issues with `query`")
98103
cmdutil.AddJSONFlags(cmd, &opts.Exporter, api.IssueFields)
99104

‎pkg/cmd/pr/list/list.go‎

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -53,22 +53,25 @@ func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Comman
5353

5454
cmd := &cobra.Command{
5555
Use: "list",
56-
Short: "List and filter pull requests in this repository",
56+
Short: "List pull requests in a repository",
57+
Long: heredoc.Doc(`
58+
List pull requests in a GitHub repository.
59+
60+
The search query syntax is documented here:
61+
<https://docs.github.com/en/search-github/searching-on-github/searching-issues-and-pull-requests>
62+
`),
5763
Example: heredoc.Doc(`
5864
List PRs authored by you
5965
$ gh pr list --author "@me"
6066
61-
List PRs assigned to you
62-
$ gh pr list --assignee "@me"
63-
64-
List PRs by label, combining multiple labels with AND
67+
List only PRs with all of the given labels
6568
$ gh pr list --label bug --label "priority 1"
6669
67-
List PRs using search syntax
70+
Filter PRs using search syntax
6871
$ gh pr list --search "status:success review:required"
6972
70-
Open the list of PRs in a web browser
71-
$ gh pr list --web
73+
Find a PR that introduced a given commit
74+
$ gh pr list --search "<SHA>" --state merged
7275
`),
7376
Aliases: []string{"ls"},
7477
Args: cmdutil.NoArgsQuoteReminder,
@@ -99,15 +102,15 @@ func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Comman
99102
},
100103
}
101104

102-
cmd.Flags().BoolVarP(&opts.WebMode, "web", "w", false, "Open the browser to list the pull requests")
105+
cmd.Flags().BoolVarP(&opts.WebMode, "web", "w", false, "List pull requests in the web browser")
103106
cmd.Flags().IntVarP(&opts.LimitResults, "limit", "L", 30, "Maximum number of items to fetch")
104107
cmd.Flags().StringVarP(&opts.State, "state", "s", "open", "Filter by state: {open|closed|merged|all}")
105108
_ = cmd.RegisterFlagCompletionFunc("state", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) {
106109
return []string{"open", "closed", "merged", "all"}, cobra.ShellCompDirectiveNoFileComp
107110
})
108111
cmd.Flags().StringVarP(&opts.BaseBranch, "base", "B", "", "Filter by base branch")
109112
cmd.Flags().StringVarP(&opts.HeadBranch, "head", "H", "", "Filter by head branch")
110-
cmd.Flags().StringSliceVarP(&opts.Labels, "label", "l", nil, "Filter by labels")
113+
cmd.Flags().StringSliceVarP(&opts.Labels, "label", "l", nil, "Filter by label")
111114
cmd.Flags().StringVarP(&opts.Author, "author", "A", "", "Filter by author")
112115
cmd.Flags().StringVar(&opts.AppAuthor, "app", "", "Filter by GitHub App author")
113116
cmd.Flags().StringVarP(&opts.Assignee, "assignee", "a", "", "Filter by assignee")

0 commit comments

Comments
 (0)