From 17d336e005e45e3d9e3b37173dce96f487ffb6f5 Mon Sep 17 00:00:00 2001 From: Yukai Chou Date: Fri, 10 Nov 2023 14:52:57 +0800 Subject: [PATCH 01/29] Wrap cli flags in backticks uniformly --- pkg/cmd/alias/set/set.go | 6 +++--- pkg/cmd/auth/logout/logout.go | 6 +++--- pkg/cmd/auth/refresh/refresh.go | 10 +++++----- pkg/cmd/extension/command.go | 12 ++++++------ pkg/cmd/gist/create/create.go | 6 +++--- pkg/cmd/issue/view/view.go | 6 +++--- pkg/cmd/label/clone.go | 6 +++--- pkg/cmd/label/create.go | 6 +++--- pkg/cmd/pr/diff/diff.go | 6 +++--- pkg/cmd/pr/merge/merge.go | 6 +++--- pkg/cmd/pr/ready/ready.go | 6 +++--- pkg/cmd/pr/view/view.go | 6 +++--- pkg/cmd/project/item-edit/item_edit.go | 6 +++--- pkg/cmd/release/download/download.go | 8 ++++---- pkg/cmd/repo/edit/edit.go | 2 +- pkg/cmd/ruleset/check/check.go | 6 +++--- pkg/cmd/ruleset/list/list.go | 10 +++++----- pkg/cmd/ruleset/view/view.go | 6 +++--- pkg/cmd/workflow/run/run.go | 6 +++--- 19 files changed, 63 insertions(+), 63 deletions(-) diff --git a/pkg/cmd/alias/set/set.go b/pkg/cmd/alias/set/set.go index 77de9ca5d..840df5770 100644 --- a/pkg/cmd/alias/set/set.go +++ b/pkg/cmd/alias/set/set.go @@ -35,7 +35,7 @@ func NewCmdSet(f *cmdutil.Factory, runF func(*SetOptions) error) *cobra.Command cmd := &cobra.Command{ Use: "set ", Short: "Create a shortcut for a gh command", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Define a word that will expand to a full gh command when invoked. The expansion may specify additional arguments and flags. If the expansion includes @@ -46,10 +46,10 @@ func NewCmdSet(f *cmdutil.Factory, runF func(*SetOptions) error) *cobra.Command Use "-" as expansion argument to read the expansion string from standard input. This is useful to avoid quoting issues when defining expansions. - If the expansion starts with "!" or if "--shell" was given, the expansion is a shell + If the expansion starts with "!" or if %[1]s--shell%[1]s was given, the expansion is a shell expression that will be evaluated through the "sh" interpreter when the alias is 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 $ gh alias set pv 'pr view' diff --git a/pkg/cmd/auth/logout/logout.go b/pkg/cmd/auth/logout/logout.go index c871a5333..b2afc9a6c 100644 --- a/pkg/cmd/auth/logout/logout.go +++ b/pkg/cmd/auth/logout/logout.go @@ -33,11 +33,11 @@ func NewCmdLogout(f *cmdutil.Factory, runF func(*LogoutOptions) error) *cobra.Co Use: "logout", Args: cobra.ExactArgs(0), Short: "Log out of a GitHub host", - Long: heredoc.Doc(`Remove authentication for a GitHub host. + Long: heredoc.Docf(`Remove authentication for a GitHub host. This command removes the authentication configuration for a host either specified - interactively or via --hostname. - `), + interactively or via %[1]s--hostname%[1]s. + `, "`"), Example: heredoc.Doc(` $ gh auth logout # => select what host to log out of via a prompt diff --git a/pkg/cmd/auth/refresh/refresh.go b/pkg/cmd/auth/refresh/refresh.go index 870871284..a74bd18fb 100644 --- a/pkg/cmd/auth/refresh/refresh.go +++ b/pkg/cmd/auth/refresh/refresh.go @@ -60,19 +60,19 @@ func NewCmdRefresh(f *cmdutil.Factory, runF func(*RefreshOptions) error) *cobra. Use: "refresh", Args: cobra.ExactArgs(0), Short: "Refresh stored authentication credentials", - Long: heredoc.Doc(`Expand or fix the permission scopes for stored credentials. + Long: heredoc.Docf(`Expand or fix the permission scopes for stored credentials. - The --scopes flag accepts a comma separated list of scopes you want + The %[1]s--scopes%[1]s flag accepts a comma separated list of scopes you want your gh credentials to have. If no scopes are provided, the command maintains previously added scopes. - The --remove-scopes flag accepts a comma separated list of scopes you + The %[1]s--remove-scopes%[1]s flag accepts a comma separated list of scopes you want to remove from your gh credentials. Scope removal is idempotent. The minimum set of scopes ("repo", "read:org" and "gist") cannot be removed. - The --reset-scopes flag resets the scopes for your gh credentials to + The %[1]s--reset-scopes%[1]s flag resets the scopes for your gh credentials to the default set of scopes for your auth flow. - `), + `, "`"), Example: heredoc.Doc(` $ gh auth refresh --scopes write:org,read:public_key # => open a browser to add write:org and read:public_key scopes diff --git a/pkg/cmd/extension/command.go b/pkg/cmd/extension/command.go index c2ed18985..e8e4ecc0b 100644 --- a/pkg/cmd/extension/command.go +++ b/pkg/cmd/extension/command.go @@ -93,12 +93,12 @@ func NewCmdExtension(f *cmdutil.Factory) *cobra.Command { cmd := &cobra.Command{ Use: "search []", Short: "Search extensions to the GitHub CLI", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Search for gh extensions. With no arguments, this command prints out the first 30 extensions available to install sorted by number of stars. More extensions can - be fetched by specifying a higher limit with the --limit flag. + be fetched by specifying a higher limit with the %[1]s--limit%[1]s flag. When connected to a terminal, this command prints out three columns. The first has a ✓ if the extension is already installed locally. The @@ -122,7 +122,7 @@ func NewCmdExtension(f *cmdutil.Factory) *cobra.Command { see: gh ext list - `), + `, "`"), Example: heredoc.Doc(` # List the first 30 extensions sorted by star count, descending $ gh ext search @@ -431,7 +431,7 @@ func NewCmdExtension(f *cmdutil.Factory) *cobra.Command { cmd := &cobra.Command{ Use: "browse", Short: "Enter a UI for browsing, adding, and removing extensions", - Long: heredoc.Doc(` + Long: heredoc.Docf(` This command will take over your terminal and run a fully interactive interface for browsing, adding, and removing gh extensions. A terminal width greater than 100 columns is recommended. @@ -441,7 +441,7 @@ func NewCmdExtension(f *cmdutil.Factory) *cobra.Command { Press q to quit. - Running this command with --single-column should make this command + Running this command with %[1]s--single-column%[1]s should make this command more intelligible for users who rely on assistive technology like screen readers or high zoom. @@ -450,7 +450,7 @@ func NewCmdExtension(f *cmdutil.Factory) *cobra.Command { gh ext search along with gh ext install, gh ext remove, and gh repo view. - `), + `, "`"), Args: cobra.NoArgs, RunE: func(cmd *cobra.Command, args []string) error { if !io.CanPrompt() { diff --git a/pkg/cmd/gist/create/create.go b/pkg/cmd/gist/create/create.go index 4154acf9c..29f46b9ff 100644 --- a/pkg/cmd/gist/create/create.go +++ b/pkg/cmd/gist/create/create.go @@ -50,14 +50,14 @@ func NewCmdCreate(f *cmdutil.Factory, runF func(*CreateOptions) error) *cobra.Co cmd := &cobra.Command{ Use: "create [... | -]", Short: "Create a new gist", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Create a new GitHub gist with given contents. Gists can be created from one or multiple files. Alternatively, pass "-" as file name to read from standard input. - By default, gists are secret; use '--public' to make publicly listed ones. - `), + 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 $ gh gist create --public hello.py diff --git a/pkg/cmd/issue/view/view.go b/pkg/cmd/issue/view/view.go index 83132291f..58341a98e 100644 --- a/pkg/cmd/issue/view/view.go +++ b/pkg/cmd/issue/view/view.go @@ -48,11 +48,11 @@ func NewCmdView(f *cmdutil.Factory, runF func(*ViewOptions) error) *cobra.Comman cmd := &cobra.Command{ Use: "view { | }", Short: "View an issue", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Display the title, body, and other information about an issue. - With '--web', open the issue in a web browser instead. - `), + With %[1]s--web%[1]s, open the issue in a web browser instead. + `, "`"), Args: cobra.ExactArgs(1), RunE: func(cmd *cobra.Command, args []string) error { // support `-R, --repo` override diff --git a/pkg/cmd/label/clone.go b/pkg/cmd/label/clone.go index 302de145a..81ab76958 100644 --- a/pkg/cmd/label/clone.go +++ b/pkg/cmd/label/clone.go @@ -34,7 +34,7 @@ func newCmdClone(f *cmdutil.Factory, runF func(*cloneOptions) error) *cobra.Comm cmd := &cobra.Command{ Use: "clone ", Short: "Clones labels from one repository to another", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Clones labels from a source repository to a destination repository on GitHub. By default, the destination repository is the current repository. @@ -44,8 +44,8 @@ func newCmdClone(f *cmdutil.Factory, runF func(*cloneOptions) error) *cobra.Comm Labels from the source repository that already exist in the destination repository will be skipped. You can overwrite existing labels in the - destination repository using the --force flag. - `), + 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 $ gh label clone cli/cli --force diff --git a/pkg/cmd/label/create.go b/pkg/cmd/label/create.go index 0a88fbcab..784b8f40f 100644 --- a/pkg/cmd/label/create.go +++ b/pkg/cmd/label/create.go @@ -57,14 +57,14 @@ func newCmdCreate(f *cmdutil.Factory, runF func(*createOptions) error) *cobra.Co cmd := &cobra.Command{ Use: "create ", Short: "Create a new label", - Long: heredoc.Doc(` - Create a new label on GitHub, or updates an existing one with --force. + Long: heredoc.Docf(` + Create a new label on GitHub, or updates an existing one with %[1]s--force%[1]s. Must specify name for the label. The description and color are optional. If a color isn't provided, a random one will be chosen. The label color needs to be 6 character hex value. - `), + `, "`"), Example: heredoc.Doc(` # create new bug label $ gh label create bug --description "Something isn't working" --color E99695 diff --git a/pkg/cmd/pr/diff/diff.go b/pkg/cmd/pr/diff/diff.go index ff09c6388..c837a530a 100644 --- a/pkg/cmd/pr/diff/diff.go +++ b/pkg/cmd/pr/diff/diff.go @@ -50,14 +50,14 @@ func NewCmdDiff(f *cmdutil.Factory, runF func(*DiffOptions) error) *cobra.Comman cmd := &cobra.Command{ Use: "diff [ | | ]", Short: "View changes in a pull request", - Long: heredoc.Doc(` + Long: heredoc.Docf(` View changes in a pull request. Without an argument, the pull request that belongs to the current branch is selected. - With '--web', open the pull request diff in a web browser instead. - `), + With %[1]s--web%[1]s flag, open the pull request diff in a web browser instead. + `, "`"), Args: cobra.MaximumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { opts.Finder = shared.NewFinder(f) diff --git a/pkg/cmd/pr/merge/merge.go b/pkg/cmd/pr/merge/merge.go index a23dc7390..d03d55089 100644 --- a/pkg/cmd/pr/merge/merge.go +++ b/pkg/cmd/pr/merge/merge.go @@ -78,7 +78,7 @@ func NewCmdMerge(f *cmdutil.Factory, runF func(*MergeOptions) error) *cobra.Comm cmd := &cobra.Command{ Use: "merge [ | | ]", Short: "Merge a pull request", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Merge a pull request on GitHub. Without an argument, the pull request that belongs to the current branch @@ -87,8 +87,8 @@ func NewCmdMerge(f *cmdutil.Factory, runF func(*MergeOptions) error) *cobra.Comm When targeting a branch that requires a merge queue, no merge strategy is required. If required checks have not yet passed, AutoMerge will be enabled. If required checks have passed, the pull request will be added to the merge queue. - To bypass a merge queue and merge directly, pass the '--admin' flag. - `), + To bypass a merge queue and merge directly, pass the %[1]s--admin%[1]s flag. + `, "`"), Args: cobra.MaximumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { opts.Finder = shared.NewFinder(f) diff --git a/pkg/cmd/pr/ready/ready.go b/pkg/cmd/pr/ready/ready.go index ee0cfe2fd..0b98bb548 100644 --- a/pkg/cmd/pr/ready/ready.go +++ b/pkg/cmd/pr/ready/ready.go @@ -31,14 +31,14 @@ func NewCmdReady(f *cmdutil.Factory, runF func(*ReadyOptions) error) *cobra.Comm cmd := &cobra.Command{ Use: "ready [ | | ]", Short: "Mark a pull request as ready for review", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Mark a pull request as ready for review. Without an argument, the pull request that belongs to the current branch is marked as ready. - If supported by your plan, convert to draft with --undo - `), + If supported by your plan, convert to draft with %[1]s--undo%[1]s + `, "`"), Args: cobra.MaximumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { opts.Finder = shared.NewFinder(f) diff --git a/pkg/cmd/pr/view/view.go b/pkg/cmd/pr/view/view.go index 4a69de2f4..9a1eb0a8f 100644 --- a/pkg/cmd/pr/view/view.go +++ b/pkg/cmd/pr/view/view.go @@ -42,14 +42,14 @@ func NewCmdView(f *cmdutil.Factory, runF func(*ViewOptions) error) *cobra.Comman cmd := &cobra.Command{ Use: "view [ | | ]", Short: "View a pull request", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Display the title, body, and other information about a pull request. Without an argument, the pull request that belongs to the current branch is displayed. - With '--web', open the pull request in a web browser instead. - `), + With %[1]s--web%[1]s, open the pull request in a web browser instead. + `, "`"), Args: cobra.MaximumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { opts.Finder = shared.NewFinder(f) diff --git a/pkg/cmd/project/item-edit/item_edit.go b/pkg/cmd/project/item-edit/item_edit.go index c21548a4a..dcddac8f9 100644 --- a/pkg/cmd/project/item-edit/item_edit.go +++ b/pkg/cmd/project/item-edit/item_edit.go @@ -62,13 +62,13 @@ func NewCmdEditItem(f *cmdutil.Factory, runF func(config editItemConfig) error) editItemCmd := &cobra.Command{ Use: "item-edit", Short: "Edit an item in a project", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Edit either a draft issue or a project item. Both usages require the ID of the item to edit. For non-draft issues, the ID of the project is also required, and only a single field value can be updated per invocation. - Remove project item field value using "--clear" flag. - `), + 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" diff --git a/pkg/cmd/release/download/download.go b/pkg/cmd/release/download/download.go index 02519e146..7c2d88a6a 100644 --- a/pkg/cmd/release/download/download.go +++ b/pkg/cmd/release/download/download.go @@ -46,13 +46,13 @@ func NewCmdDownload(f *cmdutil.Factory, runF func(*DownloadOptions) error) *cobr cmd := &cobra.Command{ Use: "download []", Short: "Download release assets", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Download assets from a GitHub release. Without an explicit tag name argument, assets are downloaded from the - latest release in the project. In this case, "--pattern" or "--archive" - is required. - `), + latest release in the project. In this case, %[1]s--pattern%[1]s + or %[1]s--archive%[1]s is required. + `, "`"), Example: heredoc.Doc(` # download all assets from a specific release $ gh release download v1.2.3 diff --git a/pkg/cmd/repo/edit/edit.go b/pkg/cmd/repo/edit/edit.go index 112aa5131..508dea06c 100644 --- a/pkg/cmd/repo/edit/edit.go +++ b/pkg/cmd/repo/edit/edit.go @@ -101,7 +101,7 @@ func NewCmdEdit(f *cmdutil.Factory, runF func(options *EditOptions) error) *cobr Long: heredoc.Docf(` Edit repository settings. - To toggle a setting off, use the %[1]s--flag=false%[1]s syntax. + To toggle a setting off, use the %[1]s--=false%[1]s syntax. Note that changing repository visibility to private will cause loss of stars and watchers. `, "`"), diff --git a/pkg/cmd/ruleset/check/check.go b/pkg/cmd/ruleset/check/check.go index 3007fe36a..7d82990c4 100644 --- a/pkg/cmd/ruleset/check/check.go +++ b/pkg/cmd/ruleset/check/check.go @@ -43,7 +43,7 @@ func NewCmdCheck(f *cmdutil.Factory, runF func(*CheckOptions) error) *cobra.Comm cmd := &cobra.Command{ Use: "check []", Short: "View rules that would apply to a given branch", - Long: heredoc.Doc(` + Long: heredoc.Docf(` View information about GitHub rules that apply to a given branch. The provided branch name does not need to exist; rules will be displayed that would apply @@ -51,9 +51,9 @@ func NewCmdCheck(f *cmdutil.Factory, runF func(*CheckOptions) error) *cobra.Comm If no branch name is provided, then the current branch will be used. - The --default flag can be used to view rules that apply to the default branch of the + The %[1]s--default%[1]s flag can be used to view rules that apply to the default branch of the repository. - `), + `, "`"), Example: heredoc.Doc(` # View all rules that apply to the current branch $ gh ruleset check diff --git a/pkg/cmd/ruleset/list/list.go b/pkg/cmd/ruleset/list/list.go index a4b52073d..e5932d170 100644 --- a/pkg/cmd/ruleset/list/list.go +++ b/pkg/cmd/ruleset/list/list.go @@ -40,18 +40,18 @@ func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Comman cmd := &cobra.Command{ Use: "list", Short: "List rulesets for a repository or organization", - Long: heredoc.Doc(` + Long: heredoc.Docf(` List GitHub rulesets for a repository or organization. If no options are provided, the current repository's rulesets are listed. You can query a different - repository's rulesets by using the --repo flag. You can also use the --org flag to list rulesets + repository's rulesets by using the %[1]s--repo%[1]s flag. You can also use the %[1]s--org%[1]s flag to list rulesets configured for the provided organization. - Use the --parents flag to control whether rulesets configured at higher levels that also apply to the provided + Use the %[1]s--parents%[1]s flag to control whether rulesets configured at higher levels that also apply to the provided repository or organization should be returned. The default is true. - Your access token must have the admin:org scope to use the --org flag, which can be granted by running "gh auth refresh -s admin:org". - `), + Your access token must have the admin:org scope to use the %[1]s--org%[1]s flag, which can be granted by running "gh auth refresh -s admin:org". + `, "`"), Example: heredoc.Doc(` # List rulesets in the current repository $ gh ruleset list diff --git a/pkg/cmd/ruleset/view/view.go b/pkg/cmd/ruleset/view/view.go index 0b79302e5..1359b1b56 100644 --- a/pkg/cmd/ruleset/view/view.go +++ b/pkg/cmd/ruleset/view/view.go @@ -44,16 +44,16 @@ func NewCmdView(f *cmdutil.Factory, runF func(*ViewOptions) error) *cobra.Comman cmd := &cobra.Command{ Use: "view []", Short: "View information about a ruleset", - Long: heredoc.Doc(` + Long: heredoc.Docf(` View information about a GitHub ruleset. If no ID is provided, an interactive prompt will be used to choose the ruleset to view. - Use the --parents flag to control whether rulesets configured at higher + Use the %[1]s--parents%[1]s flag to control whether rulesets configured at higher levels that also apply to the provided repository or organization should be returned. The default is true. - `), + `, "`"), Example: heredoc.Doc(` # Interactively choose a ruleset to view from all rulesets that apply to the current repository $ gh ruleset view diff --git a/pkg/cmd/workflow/run/run.go b/pkg/cmd/workflow/run/run.go index 86b24ed64..9d73502e1 100644 --- a/pkg/cmd/workflow/run/run.go +++ b/pkg/cmd/workflow/run/run.go @@ -53,7 +53,7 @@ func NewCmdRun(f *cmdutil.Factory, runF func(*RunOptions) error) *cobra.Command cmd := &cobra.Command{ Use: "run [ | ]", Short: "Run a workflow by creating a workflow_dispatch event", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Create a workflow_dispatch event for a given workflow. This command will trigger GitHub Actions to run a given workflow file. The given workflow file must @@ -62,9 +62,9 @@ func NewCmdRun(f *cmdutil.Factory, runF func(*RunOptions) error) *cobra.Command If the workflow file supports inputs, they can be specified in a few ways: - Interactively - - via -f or -F flags + - via %[1]s-f/--raw-field%[1]s or %[1]s-F/--field%[1]s flags - As JSON, via STDIN - `), + `, "`"), Example: heredoc.Doc(` # Have gh prompt you for what workflow you'd like to run and interactively collect inputs $ gh workflow run From 896101678faf5dabbc4b3e9619a63fef700c2db4 Mon Sep 17 00:00:00 2001 From: Yukai Chou Date: Fri, 10 Nov 2023 15:07:34 +0800 Subject: [PATCH 02/29] Wrap cli commands in backticks uniformly --- pkg/cmd/alias/alias.go | 6 +++--- pkg/cmd/alias/imports/import.go | 8 ++++---- pkg/cmd/extension/command.go | 6 +++--- pkg/cmd/gist/clone/clone.go | 6 +++--- pkg/cmd/issue/create/create.go | 6 +++--- pkg/cmd/issue/edit/edit.go | 6 +++--- pkg/cmd/pr/create/create.go | 2 +- pkg/cmd/pr/edit/edit.go | 6 +++--- pkg/cmd/root/help_topic.go | 10 +++++----- pkg/cmd/ruleset/list/list.go | 2 +- pkg/cmd/variable/variable.go | 6 +++--- 11 files changed, 32 insertions(+), 32 deletions(-) diff --git a/pkg/cmd/alias/alias.go b/pkg/cmd/alias/alias.go index 713e7d1db..d91b4dc2d 100644 --- a/pkg/cmd/alias/alias.go +++ b/pkg/cmd/alias/alias.go @@ -14,11 +14,11 @@ func NewCmdAlias(f *cmdutil.Factory) *cobra.Command { cmd := &cobra.Command{ Use: "alias ", Short: "Create command shortcuts", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Aliases can be used to make shortcuts for gh commands or to compose multiple commands. - Run "gh help alias set" to learn more. - `), + Run %[1]sgh help alias set%[1]s to learn more. + `, "`"), } cmdutil.DisableAuthCheck(cmd) diff --git a/pkg/cmd/alias/imports/import.go b/pkg/cmd/alias/imports/import.go index ef2176d45..ee0457b78 100644 --- a/pkg/cmd/alias/imports/import.go +++ b/pkg/cmd/alias/imports/import.go @@ -34,7 +34,7 @@ func NewCmdImport(f *cmdutil.Factory, runF func(*ImportOptions) error) *cobra.Co cmd := &cobra.Command{ Use: "import [ | -]", Short: "Import aliases from a YAML file", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Import aliases from the contents of a YAML file. Aliases should be defined as a map in YAML, where the keys represent aliases and @@ -49,10 +49,10 @@ func NewCmdImport(f *cmdutil.Factory, runF func(*ImportOptions) error) *cobra.Co Use "-" to read aliases (in YAML format) from standard input. - The output from the gh command "alias list" can be used to produce a YAML file + The output from %[1]sgh alias list%[1]s can be used to produce a YAML file containing your aliases, which you can use to import them from one machine to - another. Run "gh help alias list" to learn more. - `), + another. Run %[1]sgh help alias list%[1]s to learn more. + `, "`"), Example: heredoc.Doc(` # Import aliases from a file $ gh alias import aliases.yml diff --git a/pkg/cmd/extension/command.go b/pkg/cmd/extension/command.go index e8e4ecc0b..1908ed5e5 100644 --- a/pkg/cmd/extension/command.go +++ b/pkg/cmd/extension/command.go @@ -109,13 +109,13 @@ func NewCmdExtension(f *cmdutil.Factory) *cobra.Command { word "installed" but otherwise the order and content of the columns is the same. - This command behaves similarly to 'gh search repos' but does not + This command behaves similarly to %[1]sgh search repos%[1]s but does not support as many search qualifiers. For a finer grained search of extensions, try using: gh search repos --topic "gh-extension" - and adding qualifiers as needed. See 'gh help search repos' to learn + and adding qualifiers as needed. See %[1]sgh help search repos%[1]s to learn more about repository search. For listing just the extensions that are already installed locally, @@ -449,7 +449,7 @@ func NewCmdExtension(f *cmdutil.Factory) *cobra.Command { gh ext search - along with gh ext install, gh ext remove, and gh repo view. + along with %[1]sgh ext install%[1]s, %[1]sgh ext remove%[1]s, and %[1]sgh repo view%[1]s. `, "`"), Args: cobra.NoArgs, RunE: func(cmd *cobra.Command, args []string) error { diff --git a/pkg/cmd/gist/clone/clone.go b/pkg/cmd/gist/clone/clone.go index d83560f40..a18538ae3 100644 --- a/pkg/cmd/gist/clone/clone.go +++ b/pkg/cmd/gist/clone/clone.go @@ -40,15 +40,15 @@ func NewCmdClone(f *cmdutil.Factory, runF func(*CloneOptions) error) *cobra.Comm Use: "clone [] [-- ...]", Args: cmdutil.MinimumArgs(1, "cannot clone: gist argument required"), Short: "Clone a gist locally", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Clone a GitHub gist locally. A gist can be supplied as argument in either of the following formats: - by ID, e.g. 5b0e0062eb8e9654adad7bb1d81cc75f - by URL, e.g. "https://gist.github.com/OWNER/5b0e0062eb8e9654adad7bb1d81cc75f" - Pass additional 'git clone' flags by listing them after '--'. - `), + Pass additional %[1]sgit clone%[1]s flags by listing them after '--'. + `, "`"), RunE: func(cmd *cobra.Command, args []string) error { opts.Gist = args[0] opts.GitArgs = args[1:] diff --git a/pkg/cmd/issue/create/create.go b/pkg/cmd/issue/create/create.go index 577f08728..39fc21842 100644 --- a/pkg/cmd/issue/create/create.go +++ b/pkg/cmd/issue/create/create.go @@ -56,12 +56,12 @@ func NewCmdCreate(f *cmdutil.Factory, runF func(*CreateOptions) error) *cobra.Co cmd := &cobra.Command{ Use: "create", Short: "Create a new issue", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Create an issue on GitHub. Adding an issue to projects requires authorization with the "project" scope. - To authorize, run "gh auth refresh -s project". - `), + To authorize, run %[1]sgh auth refresh -s project%[1]s. + `, "`"), Example: heredoc.Doc(` $ gh issue create --title "I found a bug" --body "Nothing works" $ gh issue create --label "bug,help wanted" diff --git a/pkg/cmd/issue/edit/edit.go b/pkg/cmd/issue/edit/edit.go index 53400fb63..3e85813f6 100644 --- a/pkg/cmd/issue/edit/edit.go +++ b/pkg/cmd/issue/edit/edit.go @@ -50,12 +50,12 @@ func NewCmdEdit(f *cmdutil.Factory, runF func(*EditOptions) error) *cobra.Comman cmd := &cobra.Command{ Use: "edit { | }", Short: "Edit issues", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Edit one or more issues within the same repository. Editing issues' projects requires authorization with the "project" scope. - To authorize, run "gh auth refresh -s project". - `), + To authorize, run %[1]sgh auth refresh -s project%[1]s. + `, "`"), Example: heredoc.Doc(` $ gh issue edit 23 --title "I found a bug" --body "Nothing works" $ gh issue edit 23 --add-label "bug,help wanted" --remove-label "core" diff --git a/pkg/cmd/pr/create/create.go b/pkg/cmd/pr/create/create.go index 890171860..cecc32fe0 100644 --- a/pkg/cmd/pr/create/create.go +++ b/pkg/cmd/pr/create/create.go @@ -119,7 +119,7 @@ func NewCmdCreate(f *cmdutil.Factory, runF func(*CreateOptions) error) *cobra.Co head branch of the pull request. Disable this with %[1]s--no-maintainer-edit%[1]s. Adding a pull request to projects requires authorization with the "project" scope. - To authorize, run "gh auth refresh -s project". + To authorize, run %[1]sgh auth refresh -s project%[1]s. `, "`"), Example: heredoc.Doc(` $ gh pr create --title "The bug is fixed" --body "Everything works again" diff --git a/pkg/cmd/pr/edit/edit.go b/pkg/cmd/pr/edit/edit.go index c606ae6bb..502b1b384 100644 --- a/pkg/cmd/pr/edit/edit.go +++ b/pkg/cmd/pr/edit/edit.go @@ -47,15 +47,15 @@ func NewCmdEdit(f *cmdutil.Factory, runF func(*EditOptions) error) *cobra.Comman cmd := &cobra.Command{ Use: "edit [ | | ]", Short: "Edit a pull request", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Edit a pull request. Without an argument, the pull request that belongs to the current branch is selected. Editing a pull request's projects requires authorization with the "project" scope. - To authorize, run "gh auth refresh -s project". - `), + To authorize, run %[1]sgh auth refresh -s project%[1]s. + `, "`"), Example: heredoc.Doc(` $ gh pr edit 23 --title "I found a bug" --body "Nothing works" $ gh pr edit 23 --add-label "bug,help wanted" --remove-label "core" diff --git a/pkg/cmd/root/help_topic.go b/pkg/cmd/root/help_topic.go index 7db694668..7fe88f866 100644 --- a/pkg/cmd/root/help_topic.go +++ b/pkg/cmd/root/help_topic.go @@ -21,7 +21,7 @@ var HelpTopics = []helpTopic{ { name: "mintty", short: "Information about using gh with MinTTY", - long: heredoc.Doc(` + long: heredoc.Docf(` MinTTY is the terminal emulator that comes by default with Git for Windows. It has known issues with gh's ability to prompt a user for input. @@ -31,12 +31,12 @@ var HelpTopics = []helpTopic{ - Reinstall Git for Windows, checking "Enable experimental support for pseudo consoles". - Use a different terminal emulator with Git for Windows like Windows Terminal. - You can run "C:\Program Files\Git\bin\bash.exe" from any terminal emulator to continue + You can run %[1]sC:\Program Files\Git\bin\bash.exe%[1]s from any terminal emulator to continue using all of the tooling in Git For Windows without MinTTY. - - Prefix invocations of gh with winpty, eg: "winpty gh auth login". + - Prefix invocations of gh with winpty, eg: %[1]swinpty gh auth login%[1]s. NOTE: this can lead to some UI bugs. - `), + `, "`"), }, { name: "environment", @@ -99,7 +99,7 @@ var HelpTopics = []helpTopic{ GH_PATH: set the path to the gh executable, useful for when gh can not properly determine its own path such as in the cygwin terminal. - `), + `, "`"), }, { name: "reference", diff --git a/pkg/cmd/ruleset/list/list.go b/pkg/cmd/ruleset/list/list.go index e5932d170..010fa315c 100644 --- a/pkg/cmd/ruleset/list/list.go +++ b/pkg/cmd/ruleset/list/list.go @@ -50,7 +50,7 @@ func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Comman Use the %[1]s--parents%[1]s flag to control whether rulesets configured at higher levels that also apply to the provided repository or organization should be returned. The default is true. - Your access token must have the admin:org scope to use the %[1]s--org%[1]s flag, which can be granted by running "gh auth refresh -s admin:org". + Your access token must have the admin:org scope to use the %[1]s--org%[1]s flag, which can be granted by running %[1]sgh auth refresh -s admin:org%[1]s. `, "`"), Example: heredoc.Doc(` # List rulesets in the current repository diff --git a/pkg/cmd/variable/variable.go b/pkg/cmd/variable/variable.go index 50a61f4e9..f064a81e3 100644 --- a/pkg/cmd/variable/variable.go +++ b/pkg/cmd/variable/variable.go @@ -13,10 +13,10 @@ func NewCmdVariable(f *cmdutil.Factory) *cobra.Command { cmd := &cobra.Command{ Use: "variable ", Short: "Manage GitHub Actions variables", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Variables can be set at the repository, environment or organization level for use in - GitHub Actions or Dependabot. Run "gh help variable set" to learn how to get started. - `), + GitHub Actions or Dependabot. Run %[1]sgh help variable set%[1]s to learn how to get started. + `, "`"), } cmdutil.EnableRepoOverride(cmd, f) From 5c4cb5023177ad73a111bc0667ac7562e0ff31e5 Mon Sep 17 00:00:00 2001 From: Yukai Chou Date: Fri, 10 Nov 2023 15:38:46 +0800 Subject: [PATCH 03/29] Wrap env variables in backticks uniformly --- pkg/cmd/root/help_topic.go | 42 +++++++++++++++++++------------------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/pkg/cmd/root/help_topic.go b/pkg/cmd/root/help_topic.go index 7fe88f866..4b5841d8e 100644 --- a/pkg/cmd/root/help_topic.go +++ b/pkg/cmd/root/help_topic.go @@ -41,63 +41,63 @@ var HelpTopics = []helpTopic{ { name: "environment", short: "Environment variables that can be used with gh", - long: heredoc.Doc(` - GH_TOKEN, GITHUB_TOKEN (in order of precedence): an authentication token for github.com + long: heredoc.Docf(` + %[1]sGH_TOKEN%[1]s, %[1]sGITHUB_TOKEN%[1]s (in order of precedence): an authentication token for github.com API requests. Setting this avoids being prompted to authenticate and takes precedence over previously stored credentials. - GH_ENTERPRISE_TOKEN, GITHUB_ENTERPRISE_TOKEN (in order of precedence): an authentication - token for API requests to GitHub Enterprise. When setting this, also set GH_HOST. + %[1]sGH_ENTERPRISE_TOKEN%[1]s, %[1]sGITHUB_ENTERPRISE_TOKEN%[1]s (in order of precedence): an authentication + token for API requests to GitHub Enterprise. When setting this, also set %[1]sGH_HOST%[1]s. - GH_HOST: specify the GitHub hostname for commands that would otherwise assume the + %[1]sGH_HOST%[1]s: specify the GitHub hostname for commands that would otherwise assume the "github.com" host when not in a context of an existing repository. When setting this, - also set GH_ENTERPRISE_TOKEN. + also set %[1]sGH_ENTERPRISE_TOKEN%[1]s. - GH_REPO: specify the GitHub repository in the "[HOST/]OWNER/REPO" format for commands + %[1]sGH_REPO%[1]s: specify the GitHub repository in the "[HOST/]OWNER/REPO" format for commands that otherwise operate on a local repository. - GH_EDITOR, GIT_EDITOR, VISUAL, EDITOR (in order of precedence): the editor tool to use + %[1]sGH_EDITOR%[1]s, %[1]sGIT_EDITOR%[1]s, %[1]sVISUAL%[1]s, %[1]sEDITOR%[1]s (in order of precedence): the editor tool to use for authoring text. - GH_BROWSER, BROWSER (in order of precedence): the web browser to use for opening links. + %[1]sGH_BROWSER%[1]s, %[1]sBROWSER%[1]s (in order of precedence): the web browser to use for opening links. - GH_DEBUG: set to a truthy value to enable verbose output on standard error. Set to "api" + %[1]sGH_DEBUG%[1]s: set to a truthy value to enable verbose output on standard error. Set to "api" to additionally log details of HTTP traffic. - DEBUG (deprecated): set to "1", "true", or "yes" to enable verbose output on standard + %[1]sDEBUG%[1]s (deprecated): set to "1", "true", or "yes" to enable verbose output on standard error. - GH_PAGER, PAGER (in order of precedence): a terminal paging program to send standard output + %[1]sGH_PAGER%[1]s, %[1]sPAGER%[1]s (in order of precedence): a terminal paging program to send standard output to, e.g. "less". - GLAMOUR_STYLE: the style to use for rendering Markdown. See + %[1]sGLAMOUR_STYLE%[1]s: the style to use for rendering Markdown. See - NO_COLOR: set to any value to avoid printing ANSI escape sequences for color output. + %[1]sNO_COLOR%[1]s: set to any value to avoid printing ANSI escape sequences for color output. - CLICOLOR: set to "0" to disable printing ANSI colors in output. + %[1]sCLICOLOR%[1]s: set to "0" to disable printing ANSI colors in output. - CLICOLOR_FORCE: set to a value other than "0" to keep ANSI colors in output + %[1]sCLICOLOR_FORCE%[1]s: set to a value other than "0" to keep ANSI colors in output even when the output is piped. - GH_FORCE_TTY: set to any value to force terminal-style output even when the output is + %[1]sGH_FORCE_TTY%[1]s: set to any value to force terminal-style output even when the output is redirected. When the value is a number, it is interpreted as the number of columns available in the viewport. When the value is a percentage, it will be applied against the number of columns available in the current viewport. - GH_NO_UPDATE_NOTIFIER: set to any value to disable update notifications. By default, gh + %[1]sGH_NO_UPDATE_NOTIFIER%[1]s: set to any value to disable update notifications. By default, gh checks for new releases once every 24 hours and displays an upgrade notice on standard error if a newer version was found. - GH_CONFIG_DIR: the directory where gh will store configuration files. If not specified, + %[1]sGH_CONFIG_DIR%[1]s: the directory where gh will store configuration files. If not specified, the default value will be one of the following paths (in order of precedence): - "$XDG_CONFIG_HOME/gh" (if $XDG_CONFIG_HOME is set), - "$AppData/GitHub CLI" (on Windows if $AppData is set), or - "$HOME/.config/gh". - GH_PROMPT_DISABLED: set to any value to disable interactive prompting in the terminal. + %[1]sGH_PROMPT_DISABLED%[1]s: set to any value to disable interactive prompting in the terminal. - GH_PATH: set the path to the gh executable, useful for when gh can not properly determine + %[1]sGH_PATH%[1]s: set the path to the gh executable, useful for when gh can not properly determine its own path such as in the cygwin terminal. `, "`"), }, From b70c28ba2039a064e9064b7dbb30d6d96cad1e73 Mon Sep 17 00:00:00 2001 From: Yukai Chou Date: Fri, 10 Nov 2023 15:35:53 +0800 Subject: [PATCH 04/29] Misc docs improvements --- pkg/cmd/alias/set/set.go | 2 +- pkg/cmd/codespace/ssh.go | 8 ++++---- pkg/cmd/extension/command.go | 4 ++-- pkg/cmd/gist/clone/clone.go | 2 +- pkg/cmd/pr/merge/merge.go | 2 +- pkg/cmd/ruleset/list/list.go | 2 +- pkg/cmd/run/rerun/rerun.go | 2 +- pkg/cmd/workflow/run/run.go | 6 +++--- 8 files changed, 14 insertions(+), 14 deletions(-) diff --git a/pkg/cmd/alias/set/set.go b/pkg/cmd/alias/set/set.go index 840df5770..2f6eef395 100644 --- a/pkg/cmd/alias/set/set.go +++ b/pkg/cmd/alias/set/set.go @@ -47,7 +47,7 @@ func NewCmdSet(f *cmdutil.Factory, runF func(*SetOptions) error) *cobra.Command is useful to avoid quoting issues when defining expansions. If the expansion starts with "!" or if %[1]s--shell%[1]s was given, the expansion is a shell - expression that will be evaluated through the "sh" interpreter when the alias is + expression that will be evaluated through the %[1]ssh%[1]s interpreter when the alias is invoked. This allows for chaining multiple commands via piping and redirection. `, "`"), Example: heredoc.Doc(` diff --git a/pkg/cmd/codespace/ssh.go b/pkg/cmd/codespace/ssh.go index 384b92bb8..ab44cf692 100644 --- a/pkg/cmd/codespace/ssh.go +++ b/pkg/cmd/codespace/ssh.go @@ -80,11 +80,11 @@ func newSSHCmd(app *App) *cobra.Command { install it in your Dockerfile or, for codespaces that use Debian-based images, you can add the following to your devcontainer.json: - "features": { - "ghcr.io/devcontainers/features/sshd:1": { - "version": "latest" + "features": { + "ghcr.io/devcontainers/features/sshd:1": { + "version": "latest" + } } - } `), Example: heredoc.Doc(` $ gh codespace ssh diff --git a/pkg/cmd/extension/command.go b/pkg/cmd/extension/command.go index 1908ed5e5..3f22066da 100644 --- a/pkg/cmd/extension/command.go +++ b/pkg/cmd/extension/command.go @@ -102,7 +102,7 @@ func NewCmdExtension(f *cmdutil.Factory) *cobra.Command { When connected to a terminal, this command prints out three columns. The first has a ✓ if the extension is already installed locally. The - second is the full name of the extension repository in NAME/OWNER + second is the full name of the extension repository in "NAME/OWNER" format. The third is the extension's description. When not connected to a terminal, the ✓ character is rendered as the @@ -300,7 +300,7 @@ func NewCmdExtension(f *cmdutil.Factory) *cobra.Command { Long: heredoc.Doc(` Install a GitHub repository locally as a GitHub CLI extension. - The repository argument can be specified in "owner/repo" format as well as a full URL. + The repository argument can be specified in "OWNER/REPO" format as well as a full URL. The URL format is useful when the repository is not hosted on github.com. To install an extension in development from the current directory, use "." as the diff --git a/pkg/cmd/gist/clone/clone.go b/pkg/cmd/gist/clone/clone.go index a18538ae3..5360080e8 100644 --- a/pkg/cmd/gist/clone/clone.go +++ b/pkg/cmd/gist/clone/clone.go @@ -47,7 +47,7 @@ func NewCmdClone(f *cmdutil.Factory, runF func(*CloneOptions) error) *cobra.Comm - by ID, e.g. 5b0e0062eb8e9654adad7bb1d81cc75f - by URL, e.g. "https://gist.github.com/OWNER/5b0e0062eb8e9654adad7bb1d81cc75f" - Pass additional %[1]sgit clone%[1]s flags by listing them after '--'. + Pass additional %[1]sgit clone%[1]s flags by listing them after "--". `, "`"), RunE: func(cmd *cobra.Command, args []string) error { opts.Gist = args[0] diff --git a/pkg/cmd/pr/merge/merge.go b/pkg/cmd/pr/merge/merge.go index d03d55089..9582ab695 100644 --- a/pkg/cmd/pr/merge/merge.go +++ b/pkg/cmd/pr/merge/merge.go @@ -85,7 +85,7 @@ func NewCmdMerge(f *cmdutil.Factory, runF func(*MergeOptions) error) *cobra.Comm is selected. When targeting a branch that requires a merge queue, no merge strategy is required. - If required checks have not yet passed, AutoMerge will be enabled. + If required checks have not yet passed, auto-merge will be enabled. If required checks have passed, the pull request will be added to the merge queue. To bypass a merge queue and merge directly, pass the %[1]s--admin%[1]s flag. `, "`"), diff --git a/pkg/cmd/ruleset/list/list.go b/pkg/cmd/ruleset/list/list.go index 010fa315c..91f5e765f 100644 --- a/pkg/cmd/ruleset/list/list.go +++ b/pkg/cmd/ruleset/list/list.go @@ -50,7 +50,7 @@ func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Comman Use the %[1]s--parents%[1]s flag to control whether rulesets configured at higher levels that also apply to the provided repository or organization should be returned. The default is true. - Your access token must have the admin:org scope to use the %[1]s--org%[1]s flag, which can be granted by running %[1]sgh auth refresh -s admin:org%[1]s. + Your access token must have the "admin:org" scope to use the %[1]s--org%[1]s flag, which can be granted by running %[1]sgh auth refresh -s admin:org%[1]s. `, "`"), Example: heredoc.Doc(` # List rulesets in the current repository diff --git a/pkg/cmd/run/rerun/rerun.go b/pkg/cmd/run/rerun/rerun.go index 56580c642..005e3443d 100644 --- a/pkg/cmd/run/rerun/rerun.go +++ b/pkg/cmd/run/rerun/rerun.go @@ -46,7 +46,7 @@ func NewCmdRerun(f *cmdutil.Factory, runF func(*RerunOptions) error) *cobra.Comm Note that due for historical reasons, the %[1]s--job%[1]s flag may not take what you expect. Specifically, when navigating to a job in the browser, the URL looks like this: - %[1]shttps://github.com///actions/runs//jobs/%[1]s. + %[1]shttps://github.com///actions/runs//jobs/%[1]s. However, this %[1]snumber%[1]s should not be used with the %[1]s--job%[1]s flag and will result in the API returning %[1]s404 NOT FOUND%[1]s. Instead, you can get the correct job IDs using the following command: diff --git a/pkg/cmd/workflow/run/run.go b/pkg/cmd/workflow/run/run.go index 9d73502e1..4f2f14b9f 100644 --- a/pkg/cmd/workflow/run/run.go +++ b/pkg/cmd/workflow/run/run.go @@ -54,10 +54,10 @@ func NewCmdRun(f *cmdutil.Factory, runF func(*RunOptions) error) *cobra.Command Use: "run [ | ]", Short: "Run a workflow by creating a workflow_dispatch event", Long: heredoc.Docf(` - Create a workflow_dispatch event for a given workflow. + Create a %[1]sworkflow_dispatch%[1]s event for a given workflow. This command will trigger GitHub Actions to run a given workflow file. The given workflow file must - support a workflow_dispatch 'on' trigger in order to be run in this way. + support a %[1]son.workflow_dispatch%[1]s trigger in order to be run in this way. If the workflow file supports inputs, they can be specified in a few ways: @@ -129,7 +129,7 @@ func NewCmdRun(f *cmdutil.Factory, runF func(*RunOptions) error) *cobra.Command }, } cmd.Flags().StringVarP(&opts.Ref, "ref", "r", "", "The branch or tag name which contains the version of the workflow file you'd like to run") - cmd.Flags().StringArrayVarP(&opts.MagicFields, "field", "F", nil, "Add a string parameter in `key=value` format, respecting @ syntax") + cmd.Flags().StringArrayVarP(&opts.MagicFields, "field", "F", nil, "Add a string parameter in `key=value` format, respecting @ syntax (see \"gh help api\").") cmd.Flags().StringArrayVarP(&opts.RawFields, "raw-field", "f", nil, "Add a string parameter in `key=value` format") cmd.Flags().BoolVar(&opts.JSON, "json", false, "Read workflow inputs as JSON via STDIN") From 8eec3e8040108d32b4e8aef22d7f13cafe7a3733 Mon Sep 17 00:00:00 2001 From: Yukai Chou Date: Thu, 16 Nov 2023 23:08:02 +0800 Subject: [PATCH 05/29] Wrap path to file in backticks --- pkg/cmd/codespace/ssh.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pkg/cmd/codespace/ssh.go b/pkg/cmd/codespace/ssh.go index ab44cf692..f44c09958 100644 --- a/pkg/cmd/codespace/ssh.go +++ b/pkg/cmd/codespace/ssh.go @@ -712,7 +712,7 @@ func newCpCmd(app *App) *cobra.Command { provided by untrusted users; see for discussion. By default, the 'cp' command will create a public/private ssh key pair to authenticate with - the codespace inside the ~/.ssh directory. + the codespace inside the %[1]s~/.ssh directory%[1]s. `, "`"), Example: heredoc.Doc(` $ gh codespace cp -e README.md 'remote:/workspaces/$RepositoryName/' From 5612d2864ef49dbc6b7bf9da9fbda6d45b83b415 Mon Sep 17 00:00:00 2001 From: Yukai Chou Date: Thu, 16 Nov 2023 23:10:46 +0800 Subject: [PATCH 06/29] Add leftovers --- pkg/cmd/codespace/ssh.go | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/pkg/cmd/codespace/ssh.go b/pkg/cmd/codespace/ssh.go index f44c09958..1086cfa56 100644 --- a/pkg/cmd/codespace/ssh.go +++ b/pkg/cmd/codespace/ssh.go @@ -53,39 +53,39 @@ func newSSHCmd(app *App) *cobra.Command { sshCmd := &cobra.Command{ Use: "ssh [...] [-- ...] []", Short: "SSH into a codespace", - Long: heredoc.Doc(` - The 'ssh' command is used to SSH into a codespace. In its simplest form, you can - run 'gh cs ssh', select a codespace interactively, and connect. + Long: heredoc.Docf(` + The %[1]sssh%[1]s command is used to SSH into a codespace. In its simplest form, you can + run %[1]sgh cs ssh%[1]s, select a codespace interactively, and connect. - The 'ssh' command will automatically create a public/private ssh key pair in the - ~/.ssh directory if you do not have an existing valid key pair. When selecting the + The %[1]sssh%[1]s command will automatically create a public/private ssh key pair in the + %[1]s~/.ssh%[1]s directory if you do not have an existing valid key pair. When selecting the key pair to use, the preferred order is: - 1. Key specified by -i in + 1. Key specified by %[1]s-i%[1]s in %[1]s%[1]s 2. Automatic key, if it already exists - 3. First valid key pair in ssh config (according to ssh -G) + 3. First valid key pair in ssh config (according to %[1]sssh -G%[1]s) 4. Automatic key, newly created - The 'ssh' command also supports deeper integration with OpenSSH using a '--config' + The %[1]sssh%[1]s command also supports deeper integration with OpenSSH using a %[1]s--config%[1]s option that generates per-codespace ssh configuration in OpenSSH format. - Including this configuration in your ~/.ssh/config improves the user experience - of tools that integrate with OpenSSH, such as bash/zsh completion of ssh hostnames, - remote path completion for scp/rsync/sshfs, git ssh remotes, and so on. + Including this configuration in your %[1]s~/.ssh/config%[1]s improves the user experience + of tools that integrate with OpenSSH, such as Bash/Zsh completion of ssh hostnames, + remote path completion for %[1]sscp%[1]s/%[1]srsync%[1]s/%[1]ssshfs%[1]s, git ssh remotes, and so on. Once that is set up (see the second example below), you can ssh to codespaces as - if they were ordinary remote hosts (using 'ssh', not 'gh cs ssh'). + if they were ordinary remote hosts (using %[1]sssh%[1]s, not %[1]sgh cs ssh%[1]s). Note that the codespace you are connecting to must have an SSH server pre-installed. If the docker image being used for the codespace does not have an SSH server, install it in your Dockerfile or, for codespaces that use Debian-based images, - you can add the following to your devcontainer.json: + you can add the following to your %[1]sdevcontainer.json%[1]s: "features": { "ghcr.io/devcontainers/features/sshd:1": { "version": "latest" } } - `), + `, "`"), Example: heredoc.Doc(` $ gh codespace ssh @@ -693,7 +693,7 @@ func newCpCmd(app *App) *cobra.Command { Use: "cp [-e] [-r] [-- [...]] ... ", Short: "Copy files between local and remote file systems", Long: heredoc.Docf(` - The cp command copies files between the local and remote file systems. + The %[1]scp%[1]s command copies files between the local and remote file systems. As with the UNIX %[1]scp%[1]s command, the first argument specifies the source and the last specifies the destination; additional sources may be specified after the first, @@ -711,7 +711,7 @@ func newCpCmd(app *App) *cobra.Command { environment variables, and backticks. For security, do not use this flag with arguments provided by untrusted users; see for discussion. - By default, the 'cp' command will create a public/private ssh key pair to authenticate with + By default, the %[1]scp%[1]s command will create a public/private ssh key pair to authenticate with the codespace inside the %[1]s~/.ssh directory%[1]s. `, "`"), Example: heredoc.Doc(` From 21bf1babdf576561b38ad3b73117a70e8d4218c7 Mon Sep 17 00:00:00 2001 From: Yukai Chou Date: Fri, 17 Nov 2023 01:31:37 +0800 Subject: [PATCH 07/29] Proof-reading --- pkg/cmd/alias/set/set.go | 2 +- pkg/cmd/api/api.go | 10 +++++----- pkg/cmd/codespace/ssh.go | 2 +- pkg/cmd/extension/command.go | 2 +- pkg/cmd/gist/clone/clone.go | 2 +- pkg/cmd/gist/create/create.go | 2 +- pkg/cmd/release/download/download.go | 4 ++-- pkg/cmd/release/upload/upload.go | 6 +++--- pkg/cmd/root/help_topic.go | 8 ++++---- pkg/cmd/run/rerun/rerun.go | 2 +- pkg/cmd/search/code/code.go | 2 +- pkg/cmd/secret/secret.go | 6 +++--- pkg/cmd/workflow/run/run.go | 4 ++-- 13 files changed, 26 insertions(+), 26 deletions(-) diff --git a/pkg/cmd/alias/set/set.go b/pkg/cmd/alias/set/set.go index 2f6eef395..13dc6c61c 100644 --- a/pkg/cmd/alias/set/set.go +++ b/pkg/cmd/alias/set/set.go @@ -43,7 +43,7 @@ func NewCmdSet(f *cmdutil.Factory, runF func(*SetOptions) error) *cobra.Command inserted appropriately. Otherwise, extra arguments will be appended to the expanded command. - Use "-" as expansion argument to read the expansion string from standard input. This + Use %[1]s-%[1]s as expansion argument to read the expansion string from standard input. This is useful to avoid quoting issues when defining expansions. If the expansion starts with "!" or if %[1]s--shell%[1]s was given, the expansion is a shell diff --git a/pkg/cmd/api/api.go b/pkg/cmd/api/api.go index 610f2f830..6432cd302 100644 --- a/pkg/cmd/api/api.go +++ b/pkg/cmd/api/api.go @@ -75,7 +75,7 @@ func NewCmdApi(f *cmdutil.Factory, runF func(*ApiOptions) error) *cobra.Command Placeholder values "{owner}", "{repo}", and "{branch}" in the endpoint argument will get replaced with values from the repository of the current - directory or the repository specified in the GH_REPO environment variable. + directory or the repository specified in the %[1]sGH_REPO%[1]s environment variable. Note that in some shells, for example PowerShell, you may need to enclose any value that contains "{...}" in quotes to prevent the shell from applying special meaning to curly braces. @@ -85,8 +85,8 @@ func NewCmdApi(f *cmdutil.Factory, runF func(*ApiOptions) error) *cobra.Command Pass one or more %[1]s-f/--raw-field%[1]s values in "key=value" format to add static string parameters to the request payload. To add non-string or placeholder-determined values, see - %[1]s--field%[1]s below. Note that adding request parameters will automatically switch the - request method to POST. To send the parameters as a GET query string instead, use + %[1]s-F/--field%[1]s below. Note that adding request parameters will automatically switch the + request method to "POST". To send the parameters as a "GET" query string instead, use %[1]s--method GET%[1]s. The %[1]s-F/--field%[1]s flag has magic type conversion based on the format of the value: @@ -96,7 +96,7 @@ func NewCmdApi(f *cmdutil.Factory, runF func(*ApiOptions) error) *cobra.Command - placeholder values "{owner}", "{repo}", and "{branch}" get populated with values from the repository of the current directory; - if the value starts with "@", the rest of the value is interpreted as a - filename to read the value from. Pass "-" to read from standard input. + filename to read the value from. Pass %[1]s-%[1]s to read from standard input. For GraphQL requests, all fields other than "query" and "operationName" are interpreted as GraphQL variables. @@ -107,7 +107,7 @@ func NewCmdApi(f *cmdutil.Factory, runF func(*ApiOptions) error) *cobra.Command value. To pass pre-constructed JSON or payloads in other formats, a request body may be read - from file specified by %[1]s--input%[1]s. Use "-" to read from standard input. When passing the + from file specified by %[1]s--input%[1]s. Use %[1]s-%[1]s to read from standard input. When passing the request body this way, any parameters specified via field flags are added to the query string of the endpoint URL. diff --git a/pkg/cmd/codespace/ssh.go b/pkg/cmd/codespace/ssh.go index 1086cfa56..45c828ce4 100644 --- a/pkg/cmd/codespace/ssh.go +++ b/pkg/cmd/codespace/ssh.go @@ -70,7 +70,7 @@ func newSSHCmd(app *App) *cobra.Command { option that generates per-codespace ssh configuration in OpenSSH format. Including this configuration in your %[1]s~/.ssh/config%[1]s improves the user experience of tools that integrate with OpenSSH, such as Bash/Zsh completion of ssh hostnames, - remote path completion for %[1]sscp%[1]s/%[1]srsync%[1]s/%[1]ssshfs%[1]s, git ssh remotes, and so on. + remote path completion for %[1]sscp/rsync/sshfs%[1]s, git ssh remotes, and so on. Once that is set up (see the second example below), you can ssh to codespaces as if they were ordinary remote hosts (using %[1]sssh%[1]s, not %[1]sgh cs ssh%[1]s). diff --git a/pkg/cmd/extension/command.go b/pkg/cmd/extension/command.go index 3f22066da..8693a6c5d 100644 --- a/pkg/cmd/extension/command.go +++ b/pkg/cmd/extension/command.go @@ -102,7 +102,7 @@ func NewCmdExtension(f *cmdutil.Factory) *cobra.Command { When connected to a terminal, this command prints out three columns. The first has a ✓ if the extension is already installed locally. The - second is the full name of the extension repository in "NAME/OWNER" + second is the full name of the extension repository in "OWNER/REPO" format. The third is the extension's description. When not connected to a terminal, the ✓ character is rendered as the diff --git a/pkg/cmd/gist/clone/clone.go b/pkg/cmd/gist/clone/clone.go index 5360080e8..ee853f96d 100644 --- a/pkg/cmd/gist/clone/clone.go +++ b/pkg/cmd/gist/clone/clone.go @@ -47,7 +47,7 @@ func NewCmdClone(f *cmdutil.Factory, runF func(*CloneOptions) error) *cobra.Comm - by ID, e.g. 5b0e0062eb8e9654adad7bb1d81cc75f - by URL, e.g. "https://gist.github.com/OWNER/5b0e0062eb8e9654adad7bb1d81cc75f" - Pass additional %[1]sgit clone%[1]s flags by listing them after "--". + Pass additional %[1]sgit clone%[1]s flags by listing them after %[1]s--%[1]s. `, "`"), RunE: func(cmd *cobra.Command, args []string) error { opts.Gist = args[0] diff --git a/pkg/cmd/gist/create/create.go b/pkg/cmd/gist/create/create.go index 29f46b9ff..5dec11cb7 100644 --- a/pkg/cmd/gist/create/create.go +++ b/pkg/cmd/gist/create/create.go @@ -53,7 +53,7 @@ func NewCmdCreate(f *cmdutil.Factory, runF func(*CreateOptions) error) *cobra.Co Long: heredoc.Docf(` Create a new GitHub gist with given contents. - Gists can be created from one or multiple files. Alternatively, pass "-" as + Gists can be created from one or multiple files. Alternatively, pass %[1]s-%[1]s as file name to read from standard input. By default, gists are secret; use %[1]s--public%[1]s to make publicly listed ones. diff --git a/pkg/cmd/release/download/download.go b/pkg/cmd/release/download/download.go index 7c2d88a6a..56e6ac72a 100644 --- a/pkg/cmd/release/download/download.go +++ b/pkg/cmd/release/download/download.go @@ -50,8 +50,8 @@ func NewCmdDownload(f *cmdutil.Factory, runF func(*DownloadOptions) error) *cobr Download assets from a GitHub release. Without an explicit tag name argument, assets are downloaded from the - latest release in the project. In this case, %[1]s--pattern%[1]s - or %[1]s--archive%[1]s is required. + latest release in the project. In this case, %[1]s--pattern%[1]s or %[1]s--archive%[1]s + is required. `, "`"), Example: heredoc.Doc(` # download all assets from a specific release diff --git a/pkg/cmd/release/upload/upload.go b/pkg/cmd/release/upload/upload.go index 12cba4542..20d087a58 100644 --- a/pkg/cmd/release/upload/upload.go +++ b/pkg/cmd/release/upload/upload.go @@ -38,12 +38,12 @@ func NewCmdUpload(f *cmdutil.Factory, runF func(*UploadOptions) error) *cobra.Co cmd := &cobra.Command{ Use: "upload ...", Short: "Upload assets to a release", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Upload asset files to a GitHub Release. - To define a display label for an asset, append text starting with '#' after the + To define a display label for an asset, append text starting with %[1]%#%[1]% after the file name. - `), + `, "`"), Args: cobra.MinimumNArgs(2), RunE: func(cmd *cobra.Command, args []string) error { // support `-R, --repo` override diff --git a/pkg/cmd/root/help_topic.go b/pkg/cmd/root/help_topic.go index 4b5841d8e..537702005 100644 --- a/pkg/cmd/root/help_topic.go +++ b/pkg/cmd/root/help_topic.go @@ -91,9 +91,9 @@ var HelpTopics = []helpTopic{ %[1]sGH_CONFIG_DIR%[1]s: the directory where gh will store configuration files. If not specified, the default value will be one of the following paths (in order of precedence): - - "$XDG_CONFIG_HOME/gh" (if $XDG_CONFIG_HOME is set), - - "$AppData/GitHub CLI" (on Windows if $AppData is set), or - - "$HOME/.config/gh". + - %[1]s$XDG_CONFIG_HOME/gh%[1]s (if %[1]s$XDG_CONFIG_HOME%[1]s is set), + - %[1]s$AppData/GitHub CLI%[1]s (on Windows if %[1]s$AppData%[1]s is set), or + - %[1]s$HOME/.config/gh%[1]s. %[1]sGH_PROMPT_DISABLED%[1]s: set to any value to disable interactive prompting in the terminal. @@ -138,7 +138,7 @@ var HelpTopics = []helpTopic{ - %[1]stablerow ...%[1]s: aligns fields in output vertically as a table - %[1]stablerender%[1]s: renders fields added by tablerow in place - %[1]stimeago