From cce2fd4a22905cc23af2222e7b499efb22c223a4 Mon Sep 17 00:00:00 2001 From: Corey Johnson Date: Thu, 5 Dec 2019 11:40:36 -0800 Subject: [PATCH 1/4] Add better usage docs --- command/issue.go | 2 +- command/pr.go | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/command/issue.go b/command/issue.go index 0dd35ca4f..bf182ecf0 100644 --- a/command/issue.go +++ b/command/issue.go @@ -55,7 +55,7 @@ var issueStatusCmd = &cobra.Command{ RunE: issueStatus, } var issueViewCmd = &cobra.Command{ - Use: "view ", + Use: "view {issue-number | url}", Args: cobra.MinimumNArgs(1), Short: "View an issue in the browser", RunE: issueView, diff --git a/command/pr.go b/command/pr.go index ccb5f13a7..83503d8a3 100644 --- a/command/pr.go +++ b/command/pr.go @@ -37,7 +37,7 @@ var prCmd = &cobra.Command{ Long: `Work with GitHub pull requests.`, } var prCheckoutCmd = &cobra.Command{ - Use: "checkout ", + Use: "checkout {pr-number | url | branch-name}", Short: "Check out a pull request in Git", Args: cobra.MinimumNArgs(1), RunE: prCheckout, @@ -53,7 +53,7 @@ var prStatusCmd = &cobra.Command{ RunE: prStatus, } var prViewCmd = &cobra.Command{ - Use: "view [pr-number]", + Use: "view {pr-number | url | branch-name}", Short: "View a pull request in the browser", RunE: prView, } From 8222e7d74fbe0e8ec8c6564f0c4b84df26cf881a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mislav=20Marohni=C4=87?= Date: Fri, 6 Dec 2019 17:59:36 +0100 Subject: [PATCH 2/4] Consistently use `<>` to denote placeholders --- command/issue.go | 2 +- command/pr.go | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/command/issue.go b/command/issue.go index bf182ecf0..0d95e88db 100644 --- a/command/issue.go +++ b/command/issue.go @@ -55,7 +55,7 @@ var issueStatusCmd = &cobra.Command{ RunE: issueStatus, } var issueViewCmd = &cobra.Command{ - Use: "view {issue-number | url}", + Use: "view { | | }", Args: cobra.MinimumNArgs(1), Short: "View an issue in the browser", RunE: issueView, diff --git a/command/pr.go b/command/pr.go index 83503d8a3..65d513f8e 100644 --- a/command/pr.go +++ b/command/pr.go @@ -37,7 +37,7 @@ var prCmd = &cobra.Command{ Long: `Work with GitHub pull requests.`, } var prCheckoutCmd = &cobra.Command{ - Use: "checkout {pr-number | url | branch-name}", + Use: "checkout { | | }", Short: "Check out a pull request in Git", Args: cobra.MinimumNArgs(1), RunE: prCheckout, @@ -53,7 +53,7 @@ var prStatusCmd = &cobra.Command{ RunE: prStatus, } var prViewCmd = &cobra.Command{ - Use: "view {pr-number | url | branch-name}", + Use: "view { | | }", Short: "View a pull request in the browser", RunE: prView, } From 4b8921f01171408978d600820d99041180b79d04 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mislav=20Marohni=C4=87?= Date: Fri, 6 Dec 2019 18:01:14 +0100 Subject: [PATCH 3/4] Consistently use `{}` to denote mutually exclusive options --- command/issue.go | 2 +- command/pr.go | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/command/issue.go b/command/issue.go index 0d95e88db..d64397344 100644 --- a/command/issue.go +++ b/command/issue.go @@ -30,7 +30,7 @@ func init() { issueCmd.AddCommand(issueListCmd) issueListCmd.Flags().StringP("assignee", "a", "", "Filter by assignee") issueListCmd.Flags().StringSliceP("label", "l", nil, "Filter by label") - issueListCmd.Flags().StringP("state", "s", "", "Filter by state (open|closed|all)") + issueListCmd.Flags().StringP("state", "s", "", "Filter by state: {open|closed|all}") issueListCmd.Flags().IntP("limit", "L", 30, "Maximum number of issues to fetch") } diff --git a/command/pr.go b/command/pr.go index 65d513f8e..8d7f3502c 100644 --- a/command/pr.go +++ b/command/pr.go @@ -25,7 +25,7 @@ func init() { prCmd.AddCommand(prViewCmd) prListCmd.Flags().IntP("limit", "L", 30, "Maximum number of items to fetch") - prListCmd.Flags().StringP("state", "s", "open", "Filter by state") + prListCmd.Flags().StringP("state", "s", "open", "Filter by state: {open|closed|merged|all}") prListCmd.Flags().StringP("base", "B", "", "Filter by base branch") prListCmd.Flags().StringSliceP("label", "l", nil, "Filter by label") prListCmd.Flags().StringP("assignee", "a", "", "Filter by assignee") From 5f90cdc80160732062f7f1cc054d0c654c8869c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mislav=20Marohni=C4=87?= Date: Fri, 6 Dec 2019 18:01:36 +0100 Subject: [PATCH 4/4] Elaborate on what is accepted as issue/PR arguments --- command/issue.go | 6 +++++- command/pr.go | 7 ++++++- 2 files changed, 11 insertions(+), 2 deletions(-) diff --git a/command/issue.go b/command/issue.go index d64397344..76057d088 100644 --- a/command/issue.go +++ b/command/issue.go @@ -37,7 +37,11 @@ func init() { var issueCmd = &cobra.Command{ Use: "issue", Short: "Create and view issues", - Long: `Work with GitHub issues`, + Long: `Work with GitHub issues. + +An issue can be supplied as argument in any of the following formats: +- by number, e.g. "123"; or +- by URL, e.g. "https://github.com///issues/123".`, } var issueCreateCmd = &cobra.Command{ Use: "create", diff --git a/command/pr.go b/command/pr.go index 8d7f3502c..53b833099 100644 --- a/command/pr.go +++ b/command/pr.go @@ -34,7 +34,12 @@ func init() { var prCmd = &cobra.Command{ Use: "pr", Short: "Create, view, and checkout pull requests", - Long: `Work with GitHub pull requests.`, + Long: `Work with GitHub pull requests. + +A pull request can be supplied as argument in any of the following formats: +- by number, e.g. "123"; +- by URL, e.g. "https://github.com///pull/123"; or +- by the name of its head branch, e.g. "patch-1" or ":patch-1".`, } var prCheckoutCmd = &cobra.Command{ Use: "checkout { | | }",