From 33c30d5bd177cec42deea54529775f09d1d090a1 Mon Sep 17 00:00:00 2001 From: Azeem Sajid Date: Thu, 27 Feb 2025 16:26:25 +0500 Subject: [PATCH 1/2] Inconsistent format of examples in help text --- pkg/cmd/alias/set/set.go | 2 +- pkg/cmd/api/api.go | 26 +++++++++---------- pkg/cmd/attestation/inspect/inspect.go | 2 +- .../attestation/trustedroot/trustedroot.go | 2 +- pkg/cmd/auth/login/login.go | 3 ++- pkg/cmd/auth/refresh/refresh.go | 11 ++++---- pkg/cmd/browse/browse.go | 16 ++++++------ pkg/cmd/cache/list/list.go | 24 ++++++++--------- pkg/cmd/codespace/ports.go | 11 +++++--- pkg/cmd/codespace/view.go | 8 +++--- pkg/cmd/config/get/get.go | 1 - pkg/cmd/extension/command.go | 10 +++---- pkg/cmd/gist/create/create.go | 10 +++---- pkg/cmd/gist/delete/delete.go | 18 ++++++------- pkg/cmd/gist/list/list.go | 4 +-- pkg/cmd/label/clone.go | 4 +-- pkg/cmd/label/create.go | 2 +- pkg/cmd/label/edit.go | 4 +-- pkg/cmd/label/list.go | 4 +-- pkg/cmd/pr/list/list.go | 8 +++--- pkg/cmd/pr/review/review.go | 8 +++--- pkg/cmd/project/close/close.go | 8 +++--- pkg/cmd/project/copy/copy.go | 4 +-- pkg/cmd/project/create/create.go | 4 +-- pkg/cmd/project/delete/delete.go | 4 +-- pkg/cmd/project/edit/edit.go | 4 +-- pkg/cmd/project/field-create/field_create.go | 8 +++--- pkg/cmd/project/field-list/field_list.go | 6 ++--- pkg/cmd/project/item-add/item_add.go | 4 +-- pkg/cmd/project/item-archive/item_archive.go | 4 +-- pkg/cmd/project/item-create/item_create.go | 4 +-- pkg/cmd/project/item-delete/item_delete.go | 4 +-- pkg/cmd/project/item-edit/item_edit.go | 8 +++--- pkg/cmd/project/item-list/item_list.go | 4 +-- pkg/cmd/project/link/link.go | 14 +++++----- pkg/cmd/project/list/list.go | 8 +++--- .../project/mark-template/mark_template.go | 8 +++--- pkg/cmd/project/project.go | 9 ++++++- pkg/cmd/project/unlink/unlink.go | 12 ++++----- pkg/cmd/project/view/view.go | 8 +++--- pkg/cmd/release/create/create.go | 20 +++++++------- pkg/cmd/release/download/download.go | 8 +++--- pkg/cmd/release/edit/edit.go | 4 +-- pkg/cmd/repo/create/create.go | 16 ++++++------ pkg/cmd/repo/credits/credits.go | 14 +++++----- pkg/cmd/repo/deploy-key/add/add.go | 2 +- pkg/cmd/repo/edit/edit.go | 10 +++---- pkg/cmd/repo/gitignore/view/view.go | 8 +++--- pkg/cmd/repo/license/view/view.go | 10 +++---- pkg/cmd/repo/setdefault/setdefault.go | 8 +++--- pkg/cmd/root/help_topic.go | 19 ++++++++------ pkg/cmd/run/watch/watch.go | 4 +-- pkg/cmd/search/code/code.go | 12 ++++----- pkg/cmd/search/commits/commits.go | 12 ++++----- pkg/cmd/search/issues/issues.go | 14 +++++----- pkg/cmd/search/prs/prs.go | 14 +++++----- pkg/cmd/search/repos/repos.go | 14 +++++----- 57 files changed, 253 insertions(+), 239 deletions(-) diff --git a/pkg/cmd/alias/set/set.go b/pkg/cmd/alias/set/set.go index c09f7c0ccb9..6d4e214225b 100644 --- a/pkg/cmd/alias/set/set.go +++ b/pkg/cmd/alias/set/set.go @@ -51,7 +51,7 @@ func NewCmdSet(f *cmdutil.Factory, runF func(*SetOptions) error) *cobra.Command invoked. This allows for chaining multiple commands via piping and redirection. `, "`"), Example: heredoc.Doc(` - # note: Command Prompt on Windows requires using double quotes for arguments + # Note: Command Prompt on Windows requires using double quotes for arguments $ gh alias set pv 'pr view' $ gh pv -w 123 #=> gh pr view -w 123 diff --git a/pkg/cmd/api/api.go b/pkg/cmd/api/api.go index fc6aabc47e0..d25b4ce6465 100644 --- a/pkg/cmd/api/api.go +++ b/pkg/cmd/api/api.go @@ -125,39 +125,39 @@ func NewCmdApi(f *cmdutil.Factory, runF func(*ApiOptions) error) *cobra.Command into an outer JSON array. `, "`"), Example: heredoc.Doc(` - # list releases in the current repository + # List releases in the current repository $ gh api repos/{owner}/{repo}/releases - # post an issue comment + # Post an issue comment $ gh api repos/{owner}/{repo}/issues/123/comments -f body='Hi from CLI' - # post nested parameter read from a file + # Post nested parameter read from a file $ gh api gists -F 'files[myfile.txt][content]=@myfile.txt' - # add parameters to a GET request + # Add parameters to a GET request $ gh api -X GET search/issues -f q='repo:cli/cli is:open remote' - # set a custom HTTP header + # Set a custom HTTP header $ gh api -H 'Accept: application/vnd.github.v3.raw+json' ... - # opt into GitHub API previews + # Opt into GitHub API previews $ gh api --preview baptiste,nebula ... - # print only specific fields from the response + # Print only specific fields from the response $ gh api repos/{owner}/{repo}/issues --jq '.[].title' - # use a template for the output + # Use a template for the output $ gh api repos/{owner}/{repo}/issues --template \ '{{range .}}{{.title}} ({{.labels | pluck "name" | join ", " | color "yellow"}}){{"\n"}}{{end}}' - # update allowed values of the "environment" custom property in a deeply nested array - gh api -X PATCH /orgs/{org}/properties/schema \ + # Update allowed values of the "environment" custom property in a deeply nested array + $ gh api -X PATCH /orgs/{org}/properties/schema \ -F 'properties[][property_name]=environment' \ -F 'properties[][default_value]=production' \ -F 'properties[][allowed_values][]=staging' \ -F 'properties[][allowed_values][]=production' - # list releases with GraphQL + # List releases with GraphQL $ gh api graphql -F owner='{owner}' -F name='{repo}' -f query=' query($name: String!, $owner: String!) { repository(owner: $owner, name: $name) { @@ -168,7 +168,7 @@ func NewCmdApi(f *cmdutil.Factory, runF func(*ApiOptions) error) *cobra.Command } ' - # list all repositories for a user + # List all repositories for a user $ gh api graphql --paginate -f query=' query($endCursor: String) { viewer { @@ -183,7 +183,7 @@ func NewCmdApi(f *cmdutil.Factory, runF func(*ApiOptions) error) *cobra.Command } ' - # get the percentage of forks for the current user + # Get the percentage of forks for the current user $ gh api graphql --paginate --slurp -f query=' query($endCursor: String) { viewer { diff --git a/pkg/cmd/attestation/inspect/inspect.go b/pkg/cmd/attestation/inspect/inspect.go index b2d0adfb747..6fbddd6da35 100644 --- a/pkg/cmd/attestation/inspect/inspect.go +++ b/pkg/cmd/attestation/inspect/inspect.go @@ -47,7 +47,7 @@ func NewInspectCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Command timestamps, and if the included signatures match the provided public key. This command cannot be used to verify a bundle. To verify a bundle, see the - %[1]sgh at verify%[1]s command. + %[1]sgh at verify%[1]s command. By default, this command prints a condensed table. To see full results, provide the %[1]s--format=json%[1]s flag. diff --git a/pkg/cmd/attestation/trustedroot/trustedroot.go b/pkg/cmd/attestation/trustedroot/trustedroot.go index 571fb0eda4d..4e55e27abac 100644 --- a/pkg/cmd/attestation/trustedroot/trustedroot.go +++ b/pkg/cmd/attestation/trustedroot/trustedroot.go @@ -57,7 +57,7 @@ func NewTrustedRootCmd(f *cmdutil.Factory, runF func(*Options) error) *cobra.Com `, "`"), Example: heredoc.Doc(` # Get a trusted_root.jsonl for both Sigstore Public Good and GitHub's instance - gh attestation trusted-root + $ gh attestation trusted-root `), RunE: func(cmd *cobra.Command, args []string) error { if opts.Hostname == "" { diff --git a/pkg/cmd/auth/login/login.go b/pkg/cmd/auth/login/login.go index da8e4b38d6e..40b2fb38256 100644 --- a/pkg/cmd/auth/login/login.go +++ b/pkg/cmd/auth/login/login.go @@ -88,7 +88,8 @@ func NewCmdLogin(f *cmdutil.Factory, runF func(*LoginOptions) error) *cobra.Comm prompting to create and upload a new key if one is not found. This can be skipped with %[1]s--skip-ssh-key%[1]s flag. - For more information on OAuth scopes, . + For more information on OAuth scopes, see + . `, "`"), Example: heredoc.Doc(` # Start interactive setup diff --git a/pkg/cmd/auth/refresh/refresh.go b/pkg/cmd/auth/refresh/refresh.go index 7a6a39ff3ab..c0050b8a33e 100644 --- a/pkg/cmd/auth/refresh/refresh.go +++ b/pkg/cmd/auth/refresh/refresh.go @@ -74,20 +74,21 @@ func NewCmdRefresh(f *cmdutil.Factory, runF func(*RefreshOptions) error) *cobra. inactive account, you will have to use %[1]sgh auth switch%[1]s to that account first before using this command, and then switch back when you are done. - For more information on OAuth scopes, . + For more information on OAuth scopes, see + . `, "`"), Example: heredoc.Doc(` + # Open a browser to add write:org and read:public_key scopes $ gh auth refresh --scopes write:org,read:public_key - # => open a browser to add write:org and read:public_key scopes + # Open a browser to ensure your authentication credentials have the correct minimum scopes $ gh auth refresh - # => open a browser to ensure your authentication credentials have the correct minimum scopes + # Open a browser to idempotently remove the delete_repo scope $ gh auth refresh --remove-scopes delete_repo - # => open a browser to idempotently remove the delete_repo scope + # Open a browser to re-authenticate with the default minimum scopes $ gh auth refresh --reset-scopes - # => open a browser to re-authenticate with the default minimum scopes `), RunE: func(cmd *cobra.Command, args []string) error { opts.Interactive = opts.IO.CanPrompt() diff --git a/pkg/cmd/browse/browse.go b/pkg/cmd/browse/browse.go index 5cfa9829941..68c97526a8d 100644 --- a/pkg/cmd/browse/browse.go +++ b/pkg/cmd/browse/browse.go @@ -72,29 +72,29 @@ func NewCmdBrowse(f *cmdutil.Factory, runF func(*BrowseOptions) error) *cobra.Co Use: "browse [ | | ]", Args: cobra.MaximumNArgs(1), Example: heredoc.Doc(` + # Open the home page of the current repository $ gh browse - #=> Open the home page of the current repository + # Open the script directory of the current repository $ gh browse script/ - #=> Open the script directory of the current repository + # Open issue or pull request 217 $ gh browse 217 - #=> Open issue or pull request 217 + # Open commit page $ gh browse 77507cd94ccafcf568f8560cfecde965fcfa63 - #=> Open commit page + # Open repository settings $ gh browse --settings - #=> Open repository settings + # Open main.go at line 312 $ gh browse main.go:312 - #=> Open main.go at line 312 + # Open main.go with the repository at head of bug-fix branch $ gh browse main.go --branch bug-fix - #=> Open main.go with the repository at head of bug-fix branch + # Open main.go with the repository at commit 775007cd $ gh browse main.go --commit=77507cd94ccafcf568f8560cfecde965fcfa63 - #=> Open main.go with the repository at commit 775007cd `), Annotations: map[string]string{ "help:arguments": heredoc.Doc(` diff --git a/pkg/cmd/cache/list/list.go b/pkg/cmd/cache/list/list.go index 902285df6b4..9f39876cbc6 100644 --- a/pkg/cmd/cache/list/list.go +++ b/pkg/cmd/cache/list/list.go @@ -41,23 +41,23 @@ func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Comman Use: "list", Short: "List GitHub Actions caches", Example: heredoc.Doc(` - # List caches for current repository - $ gh cache list + # List caches for current repository + $ gh cache list - # List caches for specific repository - $ gh cache list --repo cli/cli + # List caches for specific repository + $ gh cache list --repo cli/cli - # List caches sorted by least recently accessed - $ gh cache list --sort last_accessed_at --order asc + # List caches sorted by least recently accessed + $ gh cache list --sort last_accessed_at --order asc - # List caches that have keys matching a prefix (or that match exactly) - $ gh cache list --key key-prefix + # List caches that have keys matching a prefix (or that match exactly) + $ gh cache list --key key-prefix - # To list caches for a specific branch, replace with the actual branch name - $ gh cache list --ref refs/heads/ + # List caches for a specific branch, replace with the actual branch name + $ gh cache list --ref refs/heads/ - # To list caches for a specific pull request, replace with the actual pull request number - $ gh cache list --ref refs/pull//merge + # List caches for a specific pull request, replace with the actual pull request number + $ gh cache list --ref refs/pull//merge `), Aliases: []string{"ls"}, Args: cobra.NoArgs, diff --git a/pkg/cmd/codespace/ports.go b/pkg/cmd/codespace/ports.go index 0608f0732c9..cd6656cf4e7 100644 --- a/pkg/cmd/codespace/ports.go +++ b/pkg/cmd/codespace/ports.go @@ -10,6 +10,7 @@ import ( "strings" "time" + "github.com/MakeNowJust/heredoc" "github.com/cli/cli/v2/internal/codespaces" "github.com/cli/cli/v2/internal/codespaces/api" "github.com/cli/cli/v2/internal/codespaces/portforwarder" @@ -217,10 +218,12 @@ func getDevContainer(ctx context.Context, apiClient apiClient, codespace *api.Co func newPortsVisibilityCmd(app *App, selector *CodespaceSelector) *cobra.Command { return &cobra.Command{ - Use: "visibility :{public|private|org}...", - Short: "Change the visibility of the forwarded port", - Example: "gh codespace ports visibility 80:org 3000:private 8000:public", - Args: cobra.MinimumNArgs(1), + Use: "visibility :{public|private|org}...", + Short: "Change the visibility of the forwarded port", + Example: heredoc.Doc(` + $ gh codespace ports visibility 80:org 3000:private 8000:public + `), + Args: cobra.MinimumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { return app.UpdatePortVisibility(cmd.Context(), selector, args) }, diff --git a/pkg/cmd/codespace/view.go b/pkg/cmd/codespace/view.go index 205d5467355..0bcbc8b5b0b 100644 --- a/pkg/cmd/codespace/view.go +++ b/pkg/cmd/codespace/view.go @@ -29,16 +29,16 @@ func newViewCmd(app *App) *cobra.Command { Use: "view", Short: "View details about a codespace", Example: heredoc.Doc(` - # select a codespace from a list of all codespaces you own + # Select a codespace from a list of all codespaces you own $ gh cs view - # view the details of a specific codespace + # View the details of a specific codespace $ gh cs view -c codespace-name-12345 - # view the list of all available fields for a codespace + # View the list of all available fields for a codespace $ gh cs view --json - # view specific fields for a codespace + # View specific fields for a codespace $ gh cs view --json displayName,machineDisplayName,state `), Args: noArgsConstraint, diff --git a/pkg/cmd/config/get/get.go b/pkg/cmd/config/get/get.go index bec22a979ff..17892485c4c 100644 --- a/pkg/cmd/config/get/get.go +++ b/pkg/cmd/config/get/get.go @@ -29,7 +29,6 @@ func NewCmdConfigGet(f *cmdutil.Factory, runF func(*GetOptions) error) *cobra.Co Short: "Print the value of a given configuration key", Example: heredoc.Doc(` $ gh config get git_protocol - https `), Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { diff --git a/pkg/cmd/extension/command.go b/pkg/cmd/extension/command.go index 1c930fe5a78..793fff4766e 100644 --- a/pkg/cmd/extension/command.go +++ b/pkg/cmd/extension/command.go @@ -542,7 +542,7 @@ func NewCmdExtension(f *cmdutil.Factory) *cobra.Command { of the extension. `, "`"), Example: heredoc.Doc(` - # execute a label extension instead of the core gh label command + # Execute a label extension instead of the core gh label command $ gh extension exec label `), Args: cobra.MinimumNArgs(1), @@ -573,16 +573,16 @@ func NewCmdExtension(f *cmdutil.Factory) *cobra.Command { Short: "Create a new extension", Example: heredoc.Doc(` # Use interactively - gh extension create + $ gh extension create # Create a script-based extension - gh extension create foobar + $ gh extension create foobar # Create a Go extension - gh extension create --precompiled=go foobar + $ gh extension create --precompiled=go foobar # Create a non-Go precompiled extension - gh extension create --precompiled=other foobar + $ gh extension create --precompiled=other foobar `), Args: cobra.MaximumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { diff --git a/pkg/cmd/gist/create/create.go b/pkg/cmd/gist/create/create.go index 4403df9be79..e9d9f2c1430 100644 --- a/pkg/cmd/gist/create/create.go +++ b/pkg/cmd/gist/create/create.go @@ -59,19 +59,19 @@ func NewCmdCreate(f *cmdutil.Factory, runF func(*CreateOptions) error) *cobra.Co By default, gists are secret; use %[1]s--public%[1]s to make publicly listed ones. `, "`"), Example: heredoc.Doc(` - # publish file 'hello.py' as a public gist + # Publish file 'hello.py' as a public gist $ gh gist create --public hello.py - # create a gist with a description + # Create a gist with a description $ gh gist create hello.py -d "my Hello-World program in Python" - # create a gist containing several files + # Create a gist containing several files $ gh gist create hello.py world.py cool.txt - # read from standard input to create a gist + # Read from standard input to create a gist $ gh gist create - - # create a gist from output piped from another command + # Create a gist from output piped from another command $ cat cool.txt | gh gist create `), Args: func(cmd *cobra.Command, args []string) error { diff --git a/pkg/cmd/gist/delete/delete.go b/pkg/cmd/gist/delete/delete.go index 8b8a47540a7..58a1fbcb6a1 100644 --- a/pkg/cmd/gist/delete/delete.go +++ b/pkg/cmd/gist/delete/delete.go @@ -38,19 +38,19 @@ func NewCmdDelete(f *cmdutil.Factory, runF func(*DeleteOptions) error) *cobra.Co Use: "delete { | }", Short: "Delete a gist", Long: heredoc.Docf(` - Delete a GitHub gist. + Delete a GitHub gist. - To delete a gist interactively, use %[1]sgh gist delete%[1]s with no arguments. + To delete a gist interactively, use %[1]sgh gist delete%[1]s with no arguments. - To delete a gist non-interactively, supply the gist id or url. - `, "`"), + To delete a gist non-interactively, supply the gist id or url. + `, "`"), Example: heredoc.Doc(` - # delete a gist interactively - gh gist delete + # Delete a gist interactively + $ gh gist delete - # delete a gist non-interactively - gh gist delete 1234 - `), + # Delete a gist non-interactively + $ gh gist delete 1234 + `), Args: cobra.MaximumNArgs(1), RunE: func(c *cobra.Command, args []string) error { if !opts.IO.CanPrompt() && !opts.Confirmed { diff --git a/pkg/cmd/gist/list/list.go b/pkg/cmd/gist/list/list.go index 00a401be425..d46d4da028a 100644 --- a/pkg/cmd/gist/list/list.go +++ b/pkg/cmd/gist/list/list.go @@ -61,10 +61,10 @@ func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Comman No highlights or other color is printed when output is redirected. `, "`"), Example: heredoc.Doc(` - # list all secret gists from your user account + # List all secret gists from your user account $ gh gist list --secret - # find all gists from your user account mentioning "octo" anywhere + # Find all gists from your user account mentioning "octo" anywhere $ gh gist list --filter octo --include-content `), Aliases: []string{"ls"}, diff --git a/pkg/cmd/label/clone.go b/pkg/cmd/label/clone.go index 81ab76958aa..a02c4764ad8 100644 --- a/pkg/cmd/label/clone.go +++ b/pkg/cmd/label/clone.go @@ -47,10 +47,10 @@ func newCmdClone(f *cmdutil.Factory, runF func(*cloneOptions) error) *cobra.Comm destination repository using the %[1]s--force%[1]s flag. `, "`"), Example: heredoc.Doc(` - # clone and overwrite labels from cli/cli repository into the current repository + # Clone and overwrite labels from cli/cli repository into the current repository $ gh label clone cli/cli --force - # clone labels from cli/cli repository into a octocat/cli repository + # Clone labels from cli/cli repository into a octocat/cli repository $ gh label clone cli/cli --repo octocat/cli `), Args: cmdutil.ExactArgs(1, "cannot clone labels: source-repository argument required"), diff --git a/pkg/cmd/label/create.go b/pkg/cmd/label/create.go index 8db57a41513..9d6b2e9ee86 100644 --- a/pkg/cmd/label/create.go +++ b/pkg/cmd/label/create.go @@ -66,7 +66,7 @@ func newCmdCreate(f *cmdutil.Factory, runF func(*createOptions) error) *cobra.Co The label color needs to be 6 character hex value. `, "`"), Example: heredoc.Doc(` - # create new bug label + # Create new bug label $ gh label create bug --description "Something isn't working" --color E99695 `), Args: cmdutil.ExactArgs(1, "cannot create label: name argument required"), diff --git a/pkg/cmd/label/edit.go b/pkg/cmd/label/edit.go index beae14045cc..79eb633f531 100644 --- a/pkg/cmd/label/edit.go +++ b/pkg/cmd/label/edit.go @@ -42,10 +42,10 @@ func newCmdEdit(f *cmdutil.Factory, runF func(*editOptions) error) *cobra.Comman The label color needs to be 6 character hex value. `, "`"), Example: heredoc.Doc(` - # update the color of the bug label + # Update the color of the bug label $ gh label edit bug --color FF0000 - # rename and edit the description of the bug label + # Rename and edit the description of the bug label $ gh label edit bug --name big-bug --description "Bigger than normal bug" `), Args: cmdutil.ExactArgs(1, "cannot update label: name argument required"), diff --git a/pkg/cmd/label/list.go b/pkg/cmd/label/list.go index 7b4c95ed1db..fe1e9cdb7f6 100644 --- a/pkg/cmd/label/list.go +++ b/pkg/cmd/label/list.go @@ -42,10 +42,10 @@ func newCmdList(f *cmdutil.Factory, runF func(*listOptions) error) *cobra.Comman This behavior cannot be configured with the %[1]s--order%[1]s or %[1]s--sort%[1]s flags. `, "`"), Example: heredoc.Doc(` - # sort labels by name + # Sort labels by name $ gh label list --sort name - # find labels with "bug" in the name or description + # Find labels with "bug" in the name or description $ gh label list --search bug `), Args: cobra.NoArgs, diff --git a/pkg/cmd/pr/list/list.go b/pkg/cmd/pr/list/list.go index 61be9599839..ee708f161c1 100644 --- a/pkg/cmd/pr/list/list.go +++ b/pkg/cmd/pr/list/list.go @@ -61,16 +61,16 @@ func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Comman `), Example: heredoc.Doc(` - List PRs authored by you + # List PRs authored by you $ gh pr list --author "@me" - List only PRs with all of the given labels + # List only PRs with all of the given labels $ gh pr list --label bug --label "priority 1" - Filter PRs using search syntax + # Filter PRs using search syntax $ gh pr list --search "status:success review:required" - Find a PR that introduced a given commit + # Find a PR that introduced a given commit $ gh pr list --search "" --state merged `), Aliases: []string{"ls"}, diff --git a/pkg/cmd/pr/review/review.go b/pkg/cmd/pr/review/review.go index 4fa973a8748..25f81d97387 100644 --- a/pkg/cmd/pr/review/review.go +++ b/pkg/cmd/pr/review/review.go @@ -56,16 +56,16 @@ func NewCmdReview(f *cmdutil.Factory, runF func(*ReviewOptions) error) *cobra.Co Without an argument, the pull request that belongs to the current branch is reviewed. `), Example: heredoc.Doc(` - # approve the pull request of the current branch + # Approve the pull request of the current branch $ gh pr review --approve - # leave a review comment for the current branch + # Leave a review comment for the current branch $ gh pr review --comment -b "interesting" - # add a review for a specific pull request + # Add a review for a specific pull request $ gh pr review 123 - # request changes on a specific pull request + # Request changes on a specific pull request $ gh pr review 123 -r -b "needs more ASCII art" `), Args: cobra.MaximumNArgs(1), diff --git a/pkg/cmd/project/close/close.go b/pkg/cmd/project/close/close.go index d24278a2308..3e85596c02a 100644 --- a/pkg/cmd/project/close/close.go +++ b/pkg/cmd/project/close/close.go @@ -40,11 +40,11 @@ func NewCmdClose(f *cmdutil.Factory, runF func(config closeConfig) error) *cobra Short: "Close a project", Use: "close []", Example: heredoc.Doc(` - # close project "1" owned by monalisa - gh project close 1 --owner monalisa + # Close project "1" owned by monalisa + $ gh project close 1 --owner monalisa - # reopen closed project "1" owned by github - gh project close 1 --owner github --undo + # Reopen closed project "1" owned by github + $ gh project close 1 --owner github --undo `), Args: cobra.MaximumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { diff --git a/pkg/cmd/project/copy/copy.go b/pkg/cmd/project/copy/copy.go index 63047f0a3b2..c0f255f96d9 100644 --- a/pkg/cmd/project/copy/copy.go +++ b/pkg/cmd/project/copy/copy.go @@ -42,8 +42,8 @@ func NewCmdCopy(f *cmdutil.Factory, runF func(config copyConfig) error) *cobra.C Short: "Copy a project", Use: "copy []", Example: heredoc.Doc(` - # copy project "1" owned by monalisa to github - gh project copy 1 --source-owner monalisa --target-owner github --title "a new project" + # Copy project "1" owned by monalisa to github + $ gh project copy 1 --source-owner monalisa --target-owner github --title "a new project" `), Args: cobra.MaximumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { diff --git a/pkg/cmd/project/create/create.go b/pkg/cmd/project/create/create.go index a261cb60036..268a2555081 100644 --- a/pkg/cmd/project/create/create.go +++ b/pkg/cmd/project/create/create.go @@ -37,8 +37,8 @@ func NewCmdCreate(f *cmdutil.Factory, runF func(config createConfig) error) *cob Short: "Create a project", Use: "create", Example: heredoc.Doc(` - # create a new project owned by login monalisa - gh project create --owner monalisa --title "a new project" + # Create a new project owned by login monalisa + $ gh project create --owner monalisa --title "a new project" `), RunE: func(cmd *cobra.Command, args []string) error { client, err := client.New(f) diff --git a/pkg/cmd/project/delete/delete.go b/pkg/cmd/project/delete/delete.go index 4848a52ae84..993b94d30c9 100644 --- a/pkg/cmd/project/delete/delete.go +++ b/pkg/cmd/project/delete/delete.go @@ -38,8 +38,8 @@ func NewCmdDelete(f *cmdutil.Factory, runF func(config deleteConfig) error) *cob Short: "Delete a project", Use: "delete []", Example: heredoc.Doc(` - # delete the current user's project "1" - gh project delete 1 --owner "@me" + # Delete the current user's project "1" + $ gh project delete 1 --owner "@me" `), Args: cobra.MaximumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { diff --git a/pkg/cmd/project/edit/edit.go b/pkg/cmd/project/edit/edit.go index f303ce357b2..4eb41f98f82 100644 --- a/pkg/cmd/project/edit/edit.go +++ b/pkg/cmd/project/edit/edit.go @@ -45,8 +45,8 @@ func NewCmdEdit(f *cmdutil.Factory, runF func(config editConfig) error) *cobra.C Short: "Edit a project", Use: "edit []", Example: heredoc.Doc(` - # edit the title of monalisa's project "1" - gh project edit 1 --owner monalisa --title "New title" + # Edit the title of monalisa's project "1" + $ gh project edit 1 --owner monalisa --title "New title" `), Args: cobra.MaximumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { diff --git a/pkg/cmd/project/field-create/field_create.go b/pkg/cmd/project/field-create/field_create.go index 56a3054800f..143719f477f 100644 --- a/pkg/cmd/project/field-create/field_create.go +++ b/pkg/cmd/project/field-create/field_create.go @@ -41,11 +41,11 @@ func NewCmdCreateField(f *cmdutil.Factory, runF func(config createFieldConfig) e Short: "Create a field in a project", Use: "field-create []", Example: heredoc.Doc(` - # create a field in the current user's project "1" - gh project field-create 1 --owner "@me" --name "new field" --data-type "text" + # Create a field in the current user's project "1" + $ gh project field-create 1 --owner "@me" --name "new field" --data-type "text" - # create a field with three options to select from for owner monalisa - gh project field-create 1 --owner monalisa --name "new field" --data-type "SINGLE_SELECT" --single-select-options "one,two,three" + # Create a field with three options to select from for owner monalisa + $ gh project field-create 1 --owner monalisa --name "new field" --data-type "SINGLE_SELECT" --single-select-options "one,two,three" `), Args: cobra.MaximumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { diff --git a/pkg/cmd/project/field-list/field_list.go b/pkg/cmd/project/field-list/field_list.go index 11964cb527d..51340c68732 100644 --- a/pkg/cmd/project/field-list/field_list.go +++ b/pkg/cmd/project/field-list/field_list.go @@ -30,10 +30,10 @@ func NewCmdList(f *cmdutil.Factory, runF func(config listConfig) error) *cobra.C opts := listOpts{} listCmd := &cobra.Command{ Short: "List the fields in a project", - Use: "field-list number", + Use: "field-list []", Example: heredoc.Doc(` - # list fields in the current user's project "1" - gh project field-list 1 --owner "@me" + # List fields in the current user's project "1" + $ gh project field-list 1 --owner "@me" `), Args: cobra.MaximumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { diff --git a/pkg/cmd/project/item-add/item_add.go b/pkg/cmd/project/item-add/item_add.go index 5e4eeff1097..00c610f0db2 100644 --- a/pkg/cmd/project/item-add/item_add.go +++ b/pkg/cmd/project/item-add/item_add.go @@ -40,8 +40,8 @@ func NewCmdAddItem(f *cmdutil.Factory, runF func(config addItemConfig) error) *c Short: "Add a pull request or an issue to a project", Use: "item-add []", Example: heredoc.Doc(` - # add an item to monalisa's project "1" - gh project item-add 1 --owner monalisa --url https://github.com/monalisa/myproject/issues/23 + # Add an item to monalisa's project "1" + $ gh project item-add 1 --owner monalisa --url https://github.com/monalisa/myproject/issues/23 `), Args: cobra.MaximumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { diff --git a/pkg/cmd/project/item-archive/item_archive.go b/pkg/cmd/project/item-archive/item_archive.go index 18a820e86eb..ec19b4fcc35 100644 --- a/pkg/cmd/project/item-archive/item_archive.go +++ b/pkg/cmd/project/item-archive/item_archive.go @@ -46,8 +46,8 @@ func NewCmdArchiveItem(f *cmdutil.Factory, runF func(config archiveItemConfig) e Short: "Archive an item in a project", Use: "item-archive []", Example: heredoc.Doc(` - # archive an item in the current user's project "1" - gh project item-archive 1 --owner "@me" --id + # Archive an item in the current user's project "1" + $ gh project item-archive 1 --owner "@me" --id `), Args: cobra.MaximumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { diff --git a/pkg/cmd/project/item-create/item_create.go b/pkg/cmd/project/item-create/item_create.go index d1775172d58..dc70fe8a46d 100644 --- a/pkg/cmd/project/item-create/item_create.go +++ b/pkg/cmd/project/item-create/item_create.go @@ -40,8 +40,8 @@ func NewCmdCreateItem(f *cmdutil.Factory, runF func(config createItemConfig) err Short: "Create a draft issue item in a project", Use: "item-create []", Example: heredoc.Doc(` - # create a draft issue in the current user's project "1" - gh project item-create 1 --owner "@me" --title "new item" --body "new item body" + # Create a draft issue in the current user's project "1" + $ gh project item-create 1 --owner "@me" --title "new item" --body "new item body" `), Args: cobra.MaximumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { diff --git a/pkg/cmd/project/item-delete/item_delete.go b/pkg/cmd/project/item-delete/item_delete.go index fc0d7c5ea6a..df5df20e954 100644 --- a/pkg/cmd/project/item-delete/item_delete.go +++ b/pkg/cmd/project/item-delete/item_delete.go @@ -39,8 +39,8 @@ func NewCmdDeleteItem(f *cmdutil.Factory, runF func(config deleteItemConfig) err Short: "Delete an item from a project by ID", Use: "item-delete []", Example: heredoc.Doc(` - # delete an item in the current user's project "1" - gh project item-delete 1 --owner "@me" --id + # Delete an item in the current user's project "1" + $ gh project item-delete 1 --owner "@me" --id `), Args: cobra.MaximumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { diff --git a/pkg/cmd/project/item-edit/item_edit.go b/pkg/cmd/project/item-edit/item_edit.go index 38818b5c5b5..43aff835ab5 100644 --- a/pkg/cmd/project/item-edit/item_edit.go +++ b/pkg/cmd/project/item-edit/item_edit.go @@ -70,11 +70,11 @@ func NewCmdEditItem(f *cmdutil.Factory, runF func(config editItemConfig) error) Remove project item field value using %[1]s--clear%[1]s flag. `, "`"), Example: heredoc.Doc(` - # edit an item's text field value - gh project item-edit --id --field-id --project-id --text "new text" + # Edit an item's text field value + $ gh project item-edit --id --field-id --project-id --text "new text" - # clear an item's field value - gh project item-edit --id --field-id --project-id --clear + # Clear an item's field value + $ gh project item-edit --id --field-id --project-id --clear `), RunE: func(cmd *cobra.Command, args []string) error { opts.numberChanged = cmd.Flags().Changed("number") diff --git a/pkg/cmd/project/item-list/item_list.go b/pkg/cmd/project/item-list/item_list.go index d62eb271692..3f792f3bd38 100644 --- a/pkg/cmd/project/item-list/item_list.go +++ b/pkg/cmd/project/item-list/item_list.go @@ -32,8 +32,8 @@ func NewCmdList(f *cmdutil.Factory, runF func(config listConfig) error) *cobra.C Short: "List the items in a project", Use: "item-list []", Example: heredoc.Doc(` - # list the items in the current users's project "1" - gh project item-list 1 --owner "@me" + # List the items in the current users's project "1" + $ gh project item-list 1 --owner "@me" `), Args: cobra.MaximumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { diff --git a/pkg/cmd/project/link/link.go b/pkg/cmd/project/link/link.go index 1e334af8c7e..f2477dde480 100644 --- a/pkg/cmd/project/link/link.go +++ b/pkg/cmd/project/link/link.go @@ -41,16 +41,16 @@ func NewCmdLink(f *cmdutil.Factory, runF func(config linkConfig) error) *cobra.C opts := linkOpts{} linkCmd := &cobra.Command{ Short: "Link a project to a repository or a team", - Use: "link [] [flag]", + Use: "link []", Example: heredoc.Doc(` - # link monalisa's project 1 to her repository "my_repo" - gh project link 1 --owner monalisa --repo my_repo + # Link monalisa's project 1 to her repository "my_repo" + $ gh project link 1 --owner monalisa --repo my_repo - # link monalisa's organization's project 1 to her team "my_team" - gh project link 1 --owner my_organization --team my_team + # Link monalisa's organization's project 1 to her team "my_team" + $ gh project link 1 --owner my_organization --team my_team - # link monalisa's project 1 to the repository of current directory if neither --repo nor --team is specified - gh project link 1 + # Link monalisa's project 1 to the repository of current directory if neither --repo nor --team is specified + $ gh project link 1 `), RunE: func(cmd *cobra.Command, args []string) error { client, err := client.New(f) diff --git a/pkg/cmd/project/list/list.go b/pkg/cmd/project/list/list.go index ba6e1d747d0..01868b4c3bb 100644 --- a/pkg/cmd/project/list/list.go +++ b/pkg/cmd/project/list/list.go @@ -35,11 +35,11 @@ func NewCmdList(f *cmdutil.Factory, runF func(config listConfig) error) *cobra.C Use: "list", Short: "List the projects for an owner", Example: heredoc.Doc(` - # list the current user's projects - gh project list + # List the current user's projects + $ gh project list - # list the projects for org github including closed projects - gh project list --owner github --closed + # List the projects for org github including closed projects + $ gh project list --owner github --closed `), Aliases: []string{"ls"}, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/pkg/cmd/project/mark-template/mark_template.go b/pkg/cmd/project/mark-template/mark_template.go index 025fe2838d9..616f8428d75 100644 --- a/pkg/cmd/project/mark-template/mark_template.go +++ b/pkg/cmd/project/mark-template/mark_template.go @@ -44,11 +44,11 @@ func NewCmdMarkTemplate(f *cmdutil.Factory, runF func(config markTemplateConfig) Short: "Mark a project as a template", Use: "mark-template []", Example: heredoc.Doc(` - # mark the github org's project "1" as a template - gh project mark-template 1 --owner "github" + # Mark the github org's project "1" as a template + $ gh project mark-template 1 --owner "github" - # unmark the github org's project "1" as a template - gh project mark-template 1 --owner "github" --undo + # Unmark the github org's project "1" as a template + $ gh project mark-template 1 --owner "github" --undo `), Args: cobra.MaximumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { diff --git a/pkg/cmd/project/project.go b/pkg/cmd/project/project.go index 6dae4a897cf..6f217d56114 100644 --- a/pkg/cmd/project/project.go +++ b/pkg/cmd/project/project.go @@ -29,7 +29,14 @@ func NewCmdProject(f *cmdutil.Factory) *cobra.Command { var cmd = &cobra.Command{ Use: "project ", Short: "Work with GitHub Projects.", - Long: "Work with GitHub Projects. Note that the token you are using must have 'project' scope, which is not set by default. You can verify your token scope by running 'gh auth status' and add the project scope by running 'gh auth refresh -s project'.", + Long: heredoc.Docf(` + Work with GitHub Projects. + + Note that the token you are using must have 'project' scope, + which is not set by default. You can verify your token scope + by running 'gh auth status' and add the project scope by + running %[1]sgh auth refresh -s project%[1]s. + `, "`"), Example: heredoc.Doc(` $ gh project create --owner monalisa --title "Roadmap" $ gh project view 1 --owner cli --web diff --git a/pkg/cmd/project/unlink/unlink.go b/pkg/cmd/project/unlink/unlink.go index 7a75db6d154..d65327fdfdd 100644 --- a/pkg/cmd/project/unlink/unlink.go +++ b/pkg/cmd/project/unlink/unlink.go @@ -43,14 +43,14 @@ func NewCmdUnlink(f *cmdutil.Factory, runF func(config unlinkConfig) error) *cob Short: "Unlink a project from a repository or a team", Use: "unlink [] [flag]", Example: heredoc.Doc(` - # unlink monalisa's project 1 from her repository "my_repo" - gh project unlink 1 --owner monalisa --repo my_repo + # Unlink monalisa's project 1 from her repository "my_repo" + $ gh project unlink 1 --owner monalisa --repo my_repo - # unlink monalisa's organization's project 1 from her team "my_team" - gh project unlink 1 --owner my_organization --team my_team + # Unlink monalisa's organization's project 1 from her team "my_team" + $ gh project unlink 1 --owner my_organization --team my_team - # unlink monalisa's project 1 from the repository of current directory if neither --repo nor --team is specified - gh project unlink 1 + # Unlink monalisa's project 1 from the repository of current directory if neither --repo nor --team is specified + $ gh project unlink 1 `), RunE: func(cmd *cobra.Command, args []string) error { client, err := client.New(f) diff --git a/pkg/cmd/project/view/view.go b/pkg/cmd/project/view/view.go index 3d94b5af3a9..49056b8d766 100644 --- a/pkg/cmd/project/view/view.go +++ b/pkg/cmd/project/view/view.go @@ -34,11 +34,11 @@ func NewCmdView(f *cmdutil.Factory, runF func(config viewConfig) error) *cobra.C Short: "View a project", Use: "view []", Example: heredoc.Doc(` - # view the current user's project "1" - gh project view 1 + # View the current user's project "1" + $ gh project view 1 - # open user monalisa's project "1" in the browser - gh project view 1 --owner monalisa --web + # Open user monalisa's project "1" in the browser + $ gh project view 1 --owner monalisa --web `), Args: cobra.MaximumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { diff --git a/pkg/cmd/release/create/create.go b/pkg/cmd/release/create/create.go index 0b709e14b9f..be6d0f65a77 100644 --- a/pkg/cmd/release/create/create.go +++ b/pkg/cmd/release/create/create.go @@ -107,34 +107,34 @@ func NewCmdCreate(f *cmdutil.Factory, runF func(*CreateOptions) error) *cobra.Co effect if there are no existing releases or this is the very first release. `, "`"), Example: heredoc.Doc(` - Interactively create a release + # Interactively create a release $ gh release create - Interactively create a release from specific tag + # Interactively create a release from specific tag $ gh release create v1.2.3 - Non-interactively create a release + # Non-interactively create a release $ gh release create v1.2.3 --notes "bugfix release" - Use automatically generated release notes + # Use automatically generated release notes $ gh release create v1.2.3 --generate-notes - Use release notes from a file + # Use release notes from a file $ gh release create v1.2.3 -F release-notes.md - Use annotated tag notes + # Use annotated tag notes $ gh release create v1.2.3 --notes-from-tag - Don't mark the release as latest + # Don't mark the release as latest $ gh release create v1.2.3 --latest=false - Upload all tarballs in a directory as release assets + # Upload all tarballs in a directory as release assets $ gh release create v1.2.3 ./dist/*.tgz - Upload a release asset with a display label + # Upload a release asset with a display label $ gh release create v1.2.3 '/path/to/asset.zip#My display label' - Create a release and start a discussion + # Create a release and start a discussion $ gh release create v1.2.3 --discussion-category "General" # Create a release only if there are new commits available since the last release diff --git a/pkg/cmd/release/download/download.go b/pkg/cmd/release/download/download.go index bb0df724330..cdf6135b633 100644 --- a/pkg/cmd/release/download/download.go +++ b/pkg/cmd/release/download/download.go @@ -57,16 +57,16 @@ func NewCmdDownload(f *cmdutil.Factory, runF func(*DownloadOptions) error) *cobr is required. `, "`"), Example: heredoc.Doc(` - # download all assets from a specific release + # Download all assets from a specific release $ gh release download v1.2.3 - # download only Debian packages for the latest release + # Download only Debian packages for the latest release $ gh release download --pattern '*.deb' - # specify multiple file patterns + # Specify multiple file patterns $ gh release download -p '*.deb' -p '*.rpm' - # download the archive of the source code for a release + # Download the archive of the source code for a release $ gh release download v1.2.3 --archive=zip `), Args: cobra.MaximumNArgs(1), diff --git a/pkg/cmd/release/edit/edit.go b/pkg/cmd/release/edit/edit.go index 245041bae83..95abf5e2054 100644 --- a/pkg/cmd/release/edit/edit.go +++ b/pkg/cmd/release/edit/edit.go @@ -43,10 +43,10 @@ func NewCmdEdit(f *cmdutil.Factory, runF func(*EditOptions) error) *cobra.Comman Use: "edit ", Short: "Edit a release", Example: heredoc.Doc(` - Publish a release that was previously a draft + # Publish a release that was previously a draft $ gh release edit v1.0 --draft=false - Update the release notes from the content of a file + # Update the release notes from the content of a file $ gh release edit v1.0 --notes-file /path/to/release_notes.md `), Args: cobra.ExactArgs(1), diff --git a/pkg/cmd/repo/create/create.go b/pkg/cmd/repo/create/create.go index ba33156c8a6..cd7c56ea81d 100644 --- a/pkg/cmd/repo/create/create.go +++ b/pkg/cmd/repo/create/create.go @@ -103,17 +103,17 @@ func NewCmdCreate(f *cmdutil.Factory, runF func(*CreateOptions) error) *cobra.Co The repo is created with the configured repository default branch, see . `, "`"), Example: heredoc.Doc(` - # create a repository interactively - gh repo create + # Create a repository interactively + $ gh repo create - # create a new remote repository and clone it locally - gh repo create my-project --public --clone + # Create a new remote repository and clone it locally + $ gh repo create my-project --public --clone - # create a new remote repository in a different organization - gh repo create my-org/my-project --public + # Create a new remote repository in a different organization + $ gh repo create my-org/my-project --public - # create a remote repository from the current directory - gh repo create my-project --private --source=. --remote=upstream + # Create a remote repository from the current directory + $ gh repo create my-project --private --source=. --remote=upstream `), Args: cobra.MaximumNArgs(1), Aliases: []string{"new"}, diff --git a/pkg/cmd/repo/credits/credits.go b/pkg/cmd/repo/credits/credits.go index 7db08a2314e..a26b6a7312a 100644 --- a/pkg/cmd/repo/credits/credits.go +++ b/pkg/cmd/repo/credits/credits.go @@ -43,13 +43,13 @@ func NewCmdCredits(f *cmdutil.Factory, runF func(*CreditsOptions) error) *cobra. Short: "View credits for this tool", Long: `View animated credits for gh, the tool you are currently using :)`, Example: heredoc.Doc(` - # see a credits animation for this project + # See a credits animation for this project $ gh credits - # display a non-animated thank you + # Display a non-animated thank you $ gh credits -s - # just print the contributors, one per line + # Just print the contributors, one per line $ gh credits | cat `), Args: cobra.ExactArgs(0), @@ -79,16 +79,16 @@ func NewCmdRepoCredits(f *cmdutil.Factory, runF func(*CreditsOptions) error) *co Use: "credits []", Short: "View credits for a repository", Example: heredoc.Doc(` - # view credits for the current repository + # View credits for the current repository $ gh repo credits - # view credits for a specific repository + # View credits for a specific repository $ gh repo credits cool/repo - # print a non-animated thank you + # Print a non-animated thank you $ gh repo credits -s - # pipe to just print the contributors, one per line + # Pipe to just print the contributors, one per line $ gh repo credits | cat `), Args: cobra.MaximumNArgs(1), diff --git a/pkg/cmd/repo/deploy-key/add/add.go b/pkg/cmd/repo/deploy-key/add/add.go index dbac7dcfb1d..2466ec98abd 100644 --- a/pkg/cmd/repo/deploy-key/add/add.go +++ b/pkg/cmd/repo/deploy-key/add/add.go @@ -40,7 +40,7 @@ func NewCmdAdd(f *cmdutil.Factory, runF func(*AddOptions) error) *cobra.Command deploy keys added by GitHub CLI will be removed as well. `), Example: heredoc.Doc(` - # generate a passwordless SSH key and add it as a deploy key to a repository + # Generate a passwordless SSH key and add it as a deploy key to a repository $ ssh-keygen -t ed25519 -C "my description" -N "" -f ~/.ssh/gh-test $ gh repo deploy-key add ~/.ssh/gh-test.pub `), diff --git a/pkg/cmd/repo/edit/edit.go b/pkg/cmd/repo/edit/edit.go index daa700cfb68..94ad8868a49 100644 --- a/pkg/cmd/repo/edit/edit.go +++ b/pkg/cmd/repo/edit/edit.go @@ -119,15 +119,15 @@ func NewCmdEdit(f *cmdutil.Factory, runF func(options *EditOptions) error) *cobr When the %[1]s--visibility%[1]s flag is used, %[1]s--accept-visibility-change-consequences%[1]s flag is required. - For information on all the potential consequences, see + For information on all the potential consequences, see . `, "`"), Args: cobra.MaximumNArgs(1), Example: heredoc.Doc(` - # enable issues and wiki - gh repo edit --enable-issues --enable-wiki + # Enable issues and wiki + $ gh repo edit --enable-issues --enable-wiki - # disable projects - gh repo edit --enable-projects=false + # Disable projects + $ gh repo edit --enable-projects=false `), RunE: func(cmd *cobra.Command, args []string) error { if len(args) > 0 { diff --git a/pkg/cmd/repo/gitignore/view/view.go b/pkg/cmd/repo/gitignore/view/view.go index b22f94ed9a0..fcf83700ac1 100644 --- a/pkg/cmd/repo/gitignore/view/view.go +++ b/pkg/cmd/repo/gitignore/view/view.go @@ -41,16 +41,16 @@ func NewCmdView(f *cmdutil.Factory, runF func(*ViewOptions) error) *cobra.Comman `, "`"), Example: heredoc.Doc(` # View the Go gitignore template - gh repo gitignore view Go + $ gh repo gitignore view Go # View the Python gitignore template - gh repo gitignore view Python + $ gh repo gitignore view Python # Create a new .gitignore file using the Go template - gh repo gitignore view Go > .gitignore + $ gh repo gitignore view Go > .gitignore # Create a new .gitignore file using the Python template - gh repo gitignore view Python > .gitignore + $ gh repo gitignore view Python > .gitignore `), Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { diff --git a/pkg/cmd/repo/license/view/view.go b/pkg/cmd/repo/license/view/view.go index 5de1659b431..d3e63c241ca 100644 --- a/pkg/cmd/repo/license/view/view.go +++ b/pkg/cmd/repo/license/view/view.go @@ -43,19 +43,19 @@ func NewCmdView(f *cmdutil.Factory, runF func(*ViewOptions) error) *cobra.Comman `, "`"), Example: heredoc.Doc(` # View the MIT license from SPDX ID - gh repo license view MIT + $ gh repo license view MIT # View the MIT license from license key - gh repo license view mit + $ gh repo license view mit # View the GNU AGPL-3.0 license from SPDX ID - gh repo license view AGPL-3.0 + $ gh repo license view AGPL-3.0 # View the GNU AGPL-3.0 license from license key - gh repo license view agpl-3.0 + $ gh repo license view agpl-3.0 # Create a LICENSE.md with the MIT license - gh repo license view MIT > LICENSE.md + $ gh repo license view MIT > LICENSE.md `), Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { diff --git a/pkg/cmd/repo/setdefault/setdefault.go b/pkg/cmd/repo/setdefault/setdefault.go index ede4d00b4b0..18a9d6fc265 100644 --- a/pkg/cmd/repo/setdefault/setdefault.go +++ b/pkg/cmd/repo/setdefault/setdefault.go @@ -64,16 +64,16 @@ func NewCmdSetDefault(f *cmdutil.Factory, runF func(*SetDefaultOptions) error) * Short: "Configure default repository for this directory", Long: explainer(), Example: heredoc.Doc(` - Interactively select a default repository: + # Interactively select a default repository $ gh repo set-default - Set a repository explicitly: + # Set a repository explicitly $ gh repo set-default owner/repo - View the current default repository: + # View the current default repository $ gh repo set-default --view - Show more repository options in the interactive picker: + # Show more repository options in the interactive picker $ git remote add newrepo https://github.com/owner/repo $ gh repo set-default `), diff --git a/pkg/cmd/root/help_topic.go b/pkg/cmd/root/help_topic.go index 00e9cf552f0..2b6432ef9db 100644 --- a/pkg/cmd/root/help_topic.go +++ b/pkg/cmd/root/help_topic.go @@ -154,7 +154,7 @@ var HelpTopics = []helpTopic{ To learn more about Go templates, see: . `, "`"), example: heredoc.Doc(` - # default output format + # Default output format $ gh pr list Showing 23 of 23 open pull requests in cli/cli @@ -163,7 +163,7 @@ var HelpTopics = []helpTopic{ #125 An exciting new feature feature-branch about 2 days ago - # adding the --json flag with a list of field names + # Adding the --json flag with a list of field names $ gh pr list --json number,title,author [ { @@ -190,13 +190,14 @@ var HelpTopics = []helpTopic{ ] - # adding the --jq flag and selecting fields from the array + # Adding the --jq flag and selecting fields from the array $ gh pr list --json author --jq '.[].author.login' monalisa codercat cli-maintainer - # --jq can be used to implement more complex filtering and output changes: + + # --jq can be used to implement more complex filtering and output changes $ gh issue list --json number,title,labels --jq \ 'map(select((.labels | length) > 0)) # must have labels | map(.labels = (.labels | map(.name))) # show only the label names @@ -227,11 +228,13 @@ var HelpTopics = []helpTopic{ "title": "An exciting new feature" } ] - # using the --template flag with the hyperlink helper - gh issue list --json title,url --template '{{range .}}{{hyperlink .url .title}}{{"\n"}}{{end}}' - # adding the --template flag and modifying the display format + # Using the --template flag with the hyperlink helper + $ gh issue list --json title,url --template '{{range .}}{{hyperlink .url .title}}{{"\n"}}{{end}}' + + + # Adding the --template flag and modifying the display format $ gh pr list --json number,title,headRefName,updatedAt --template \ '{{range .}}{{tablerow (printf "#%v" .number | autocolor "green") .title .headRefName (timeago .updatedAt)}}{{end}}' @@ -240,7 +243,7 @@ var HelpTopics = []helpTopic{ #125 An exciting new feature feature-branch about 2 days ago - # a more complex example with the --template flag which formats a pull request using multiple tables with headers: + # A more complex example with the --template flag which formats a pull request using multiple tables with headers $ gh pr view 3519 --json number,title,body,reviews,assignees --template \ '{{printf "#%v" .number}} {{.title}} diff --git a/pkg/cmd/run/watch/watch.go b/pkg/cmd/run/watch/watch.go index 9f4f37c2fe5..57be01f64a9 100644 --- a/pkg/cmd/run/watch/watch.go +++ b/pkg/cmd/run/watch/watch.go @@ -53,10 +53,10 @@ func NewCmdWatch(f *cmdutil.Factory, runF func(*WatchOptions) error) *cobra.Comm `, "`"), Example: heredoc.Doc(` # Watch a run until it's done - gh run watch + $ gh run watch # Run some other command when the run is finished - gh run watch && notify-send 'run is done!' + $ gh run watch && notify-send 'run is done!' `), RunE: func(cmd *cobra.Command, args []string) error { // support `-R, --repo` override diff --git a/pkg/cmd/search/code/code.go b/pkg/cmd/search/code/code.go index e1bc73a3419..d51ec8fa6be 100644 --- a/pkg/cmd/search/code/code.go +++ b/pkg/cmd/search/code/code.go @@ -44,22 +44,22 @@ func NewCmdCode(f *cmdutil.Factory, runF func(*CodeOptions) error) *cobra.Comman are not yet available via the GitHub API. `), Example: heredoc.Doc(` - # search code matching "react" and "lifecycle" + # Search code matching "react" and "lifecycle" $ gh search code react lifecycle - # search code matching "error handling" + # Search code matching "error handling" $ gh search code "error handling" - # search code matching "deque" in Python files + # Search code matching "deque" in Python files $ gh search code deque --language=python - # search code matching "cli" in repositories owned by microsoft organization + # Search code matching "cli" in repositories owned by microsoft organization $ gh search code cli --owner=microsoft - # search code matching "panic" in the GitHub CLI repository + # Search code matching "panic" in the GitHub CLI repository $ gh search code panic --repo cli/cli - # search code matching keyword "lint" in package.json files + # Search code matching keyword "lint" in package.json files $ gh search code lint --filename package.json `), RunE: func(c *cobra.Command, args []string) error { diff --git a/pkg/cmd/search/commits/commits.go b/pkg/cmd/search/commits/commits.go index 6a9f58b8687..bc37684a2d1 100644 --- a/pkg/cmd/search/commits/commits.go +++ b/pkg/cmd/search/commits/commits.go @@ -47,22 +47,22 @@ func NewCmdCommits(f *cmdutil.Factory, runF func(*CommitsOptions) error) *cobra. `), Example: heredoc.Doc(` - # search commits matching set of keywords "readme" and "typo" + # Search commits matching set of keywords "readme" and "typo" $ gh search commits readme typo - # search commits matching phrase "bug fix" + # Search commits matching phrase "bug fix" $ gh search commits "bug fix" - # search commits committed by user "monalisa" + # Search commits committed by user "monalisa" $ gh search commits --committer=monalisa - # search commits authored by users with name "Jane Doe" + # Search commits authored by users with name "Jane Doe" $ gh search commits --author-name="Jane Doe" - # search commits matching hash "8dd03144ffdc6c0d486d6b705f9c7fba871ee7c3" + # Search commits matching hash "8dd03144ffdc6c0d486d6b705f9c7fba871ee7c3" $ gh search commits --hash=8dd03144ffdc6c0d486d6b705f9c7fba871ee7c3 - # search commits authored before February 1st, 2022 + # Search commits authored before February 1st, 2022 $ gh search commits --author-date="<2022-02-01" `), RunE: func(c *cobra.Command, args []string) error { diff --git a/pkg/cmd/search/issues/issues.go b/pkg/cmd/search/issues/issues.go index 793eecc6198..e1f4105aea4 100644 --- a/pkg/cmd/search/issues/issues.go +++ b/pkg/cmd/search/issues/issues.go @@ -36,25 +36,25 @@ func NewCmdIssues(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *c `), Example: heredoc.Doc(` - # search issues matching set of keywords "readme" and "typo" + # Search issues matching set of keywords "readme" and "typo" $ gh search issues readme typo - # search issues matching phrase "broken feature" + # Search issues matching phrase "broken feature" $ gh search issues "broken feature" - # search issues and pull requests in cli organization + # Search issues and pull requests in cli organization $ gh search issues --include-prs --owner=cli - # search open issues assigned to yourself + # Search open issues assigned to yourself $ gh search issues --assignee=@me --state=open - # search issues with numerous comments + # Search issues with numerous comments $ gh search issues --comments=">100" - # search issues without label "bug" + # Search issues without label "bug" $ gh search issues -- -label:bug - # search issues only from un-archived repositories (default is all repositories) + # Search issues only from un-archived repositories (default is all repositories) $ gh search issues --owner github --archived=false `), RunE: func(c *cobra.Command, args []string) error { diff --git a/pkg/cmd/search/prs/prs.go b/pkg/cmd/search/prs/prs.go index fa00677e613..f7a96c5bf01 100644 --- a/pkg/cmd/search/prs/prs.go +++ b/pkg/cmd/search/prs/prs.go @@ -38,25 +38,25 @@ func NewCmdPrs(f *cmdutil.Factory, runF func(*shared.IssuesOptions) error) *cobr `), Example: heredoc.Doc(` - # search pull requests matching set of keywords "fix" and "bug" + # Search pull requests matching set of keywords "fix" and "bug" $ gh search prs fix bug - # search draft pull requests in cli repository + # Search draft pull requests in cli repository $ gh search prs --repo=cli/cli --draft - # search open pull requests requesting your review + # Search open pull requests requesting your review $ gh search prs --review-requested=@me --state=open - # search merged pull requests assigned to yourself + # Search merged pull requests assigned to yourself $ gh search prs --assignee=@me --merged - # search pull requests with numerous reactions + # Search pull requests with numerous reactions $ gh search prs --reactions=">100" - # search pull requests without label "bug" + # Search pull requests without label "bug" $ gh search prs -- -label:bug - # search pull requests only from un-archived repositories (default is all repositories) + # Search pull requests only from un-archived repositories (default is all repositories) $ gh search prs --owner github --archived=false `), RunE: func(c *cobra.Command, args []string) error { diff --git a/pkg/cmd/search/repos/repos.go b/pkg/cmd/search/repos/repos.go index 88b8db13f64..0bad650d3b1 100644 --- a/pkg/cmd/search/repos/repos.go +++ b/pkg/cmd/search/repos/repos.go @@ -48,25 +48,25 @@ func NewCmdRepos(f *cmdutil.Factory, runF func(*ReposOptions) error) *cobra.Comm `), Example: heredoc.Doc(` - # search repositories matching set of keywords "cli" and "shell" + # Search repositories matching set of keywords "cli" and "shell" $ gh search repos cli shell - # search repositories matching phrase "vim plugin" + # Search repositories matching phrase "vim plugin" $ gh search repos "vim plugin" - # search repositories public repos in the microsoft organization + # Search repositories public repos in the microsoft organization $ gh search repos --owner=microsoft --visibility=public - # search repositories with a set of topics + # Search repositories with a set of topics $ gh search repos --topic=unix,terminal - # search repositories by coding language and number of good first issues + # Search repositories by coding language and number of good first issues $ gh search repos --language=go --good-first-issues=">=10" - # search repositories without topic "linux" + # Search repositories without topic "linux" $ gh search repos -- -topic:linux - # search repositories excluding archived repositories + # Search repositories excluding archived repositories $ gh search repos --archived=false `), RunE: func(c *cobra.Command, args []string) error { From 515bb96b2fe2e5fb15c7b83b61c719cf675d4e66 Mon Sep 17 00:00:00 2001 From: Azeem Sajid Date: Thu, 27 Feb 2025 17:51:05 +0500 Subject: [PATCH 2/2] Update `project` help text; fix `unlink` usage --- pkg/cmd/project/project.go | 7 +++---- pkg/cmd/project/unlink/unlink.go | 2 +- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/pkg/cmd/project/project.go b/pkg/cmd/project/project.go index 6f217d56114..cddbad9402d 100644 --- a/pkg/cmd/project/project.go +++ b/pkg/cmd/project/project.go @@ -32,10 +32,9 @@ func NewCmdProject(f *cmdutil.Factory) *cobra.Command { Long: heredoc.Docf(` Work with GitHub Projects. - Note that the token you are using must have 'project' scope, - which is not set by default. You can verify your token scope - by running 'gh auth status' and add the project scope by - running %[1]sgh auth refresh -s project%[1]s. + The minimum required scope for the token is: %[1]sproject%[1]s. + You can verify your token scope by running %[1]sgh auth status%[1]s and + add the %[1]sproject%[1]s scope by running %[1]sgh auth refresh -s project%[1]s. `, "`"), Example: heredoc.Doc(` $ gh project create --owner monalisa --title "Roadmap" diff --git a/pkg/cmd/project/unlink/unlink.go b/pkg/cmd/project/unlink/unlink.go index d65327fdfdd..8cc2c0747c0 100644 --- a/pkg/cmd/project/unlink/unlink.go +++ b/pkg/cmd/project/unlink/unlink.go @@ -41,7 +41,7 @@ func NewCmdUnlink(f *cmdutil.Factory, runF func(config unlinkConfig) error) *cob opts := unlinkOpts{} linkCmd := &cobra.Command{ Short: "Unlink a project from a repository or a team", - Use: "unlink [] [flag]", + Use: "unlink []", Example: heredoc.Doc(` # Unlink monalisa's project 1 from her repository "my_repo" $ gh project unlink 1 --owner monalisa --repo my_repo