From 07a87ca8a4620b7ba3c3ac4897204e58a2f2e944 Mon Sep 17 00:00:00 2001 From: Yukai Chou Date: Thu, 23 Nov 2023 07:07:36 +0800 Subject: [PATCH] Wrap special values and placeholders like `-` and `$1` --- pkg/cmd/alias/imports/import.go | 2 +- pkg/cmd/alias/set/set.go | 4 ++-- pkg/cmd/api/api.go | 18 +++++++++--------- pkg/cmd/codespace/ssh.go | 2 +- pkg/cmd/extension/command.go | 18 +++++++++--------- pkg/cmd/repo/clone/clone.go | 8 ++++---- pkg/cmd/repo/fork/fork.go | 6 +++--- pkg/cmd/root/help_topic.go | 12 ++++++------ pkg/cmd/ruleset/list/list.go | 2 +- pkg/cmd/ruleset/view/view.go | 2 +- 10 files changed, 37 insertions(+), 37 deletions(-) diff --git a/pkg/cmd/alias/imports/import.go b/pkg/cmd/alias/imports/import.go index ee0457b78..c70a150f3 100644 --- a/pkg/cmd/alias/imports/import.go +++ b/pkg/cmd/alias/imports/import.go @@ -47,7 +47,7 @@ func NewCmdImport(f *cmdutil.Factory, runF func(*ImportOptions) error) *cobra.Co issue list --label=enhancement - Use "-" to read aliases (in YAML format) from standard input. + Use %[1]s-%[1]s to read aliases (in YAML format) from standard input. 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 diff --git a/pkg/cmd/alias/set/set.go b/pkg/cmd/alias/set/set.go index 13dc6c61c..e2661b7f7 100644 --- a/pkg/cmd/alias/set/set.go +++ b/pkg/cmd/alias/set/set.go @@ -39,14 +39,14 @@ func NewCmdSet(f *cmdutil.Factory, runF func(*SetOptions) error) *cobra.Command 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 - positional placeholders such as "$1", extra arguments that follow the alias will be + positional placeholders such as %[1]s$1%[1]s, extra arguments that follow the alias will be inserted appropriately. Otherwise, extra arguments will be appended to the expanded command. 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 + If the expansion starts with %[1]s!%[1]s or if %[1]s--shell%[1]s was given, the expansion is a shell 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. `, "`"), diff --git a/pkg/cmd/api/api.go b/pkg/cmd/api/api.go index 6432cd302..101e289a6 100644 --- a/pkg/cmd/api/api.go +++ b/pkg/cmd/api/api.go @@ -73,17 +73,17 @@ func NewCmdApi(f *cmdutil.Factory, runF func(*ApiOptions) error) *cobra.Command The endpoint argument should either be a path of a GitHub API v3 endpoint, or "graphql" to access the GitHub API v4. - Placeholder values "{owner}", "{repo}", and "{branch}" in the endpoint + Placeholder values %[1]s{owner}%[1]s, %[1]s{repo}%[1]s, and %[1]s{branch}%[1]s in the endpoint argument will get replaced with values from the repository of the current 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 + any value that contains %[1]s{...}%[1]s in quotes to prevent the shell from applying special meaning to curly braces. The default HTTP request method is "GET" normally and "POST" if any parameters were added. Override the method with %[1]s--method%[1]s. - Pass one or more %[1]s-f/--raw-field%[1]s values in "key=value" format to add static string + Pass one or more %[1]s-f/--raw-field%[1]s values in %[1]skey=value%[1]s format to add static string parameters to the request payload. To add non-string or placeholder-determined values, see %[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 @@ -91,19 +91,19 @@ func NewCmdApi(f *cmdutil.Factory, runF func(*ApiOptions) error) *cobra.Command The %[1]s-F/--field%[1]s flag has magic type conversion based on the format of the value: - - literal values "true", "false", "null", and integer numbers get converted to + - literal values %[1]strue%[1]s, %[1]sfalse%[1]s, %[1]snull%[1]s, and integer numbers get converted to appropriate JSON types; - - placeholder values "{owner}", "{repo}", and "{branch}" get populated with values + - placeholder values %[1]s{owner}%[1]s, %[1]s{repo}%[1]s, and %[1]s{branch}%[1]s 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 + - if the value starts with %[1]s@%[1]s, the rest of the value is interpreted as a 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 + For GraphQL requests, all fields other than %[1]squery%[1]s and %[1]soperationName%[1]s are interpreted as GraphQL variables. - To pass nested parameters in the request payload, use "key[subkey]=value" syntax when + To pass nested parameters in the request payload, use %[1]skey[subkey]=value%[1]s syntax when declaring fields. To pass nested values as arrays, declare multiple fields with the - syntax "key[]=value1", "key[]=value2". To pass an empty array, use "key[]" without a + syntax %[1]skey[]=value1%[1]s, %[1]skey[]=value2%[1]s. To pass an empty array, use %[1]skey[]%[1]s without a value. To pass pre-constructed JSON or payloads in other formats, a request body may be read diff --git a/pkg/cmd/codespace/ssh.go b/pkg/cmd/codespace/ssh.go index 45c828ce4..54536ccfa 100644 --- a/pkg/cmd/codespace/ssh.go +++ b/pkg/cmd/codespace/ssh.go @@ -701,7 +701,7 @@ func newCpCmd(app *App) *cobra.Command { The %[1]s--recursive%[1]s flag is required if any source is a directory. - A "remote:" prefix on any file name argument indicates that it refers to + A %[1]sremote:%[1]s prefix on any file name argument indicates that it refers to the file system of the remote (Codespace) machine. It is resolved relative to the home directory of the remote user. diff --git a/pkg/cmd/extension/command.go b/pkg/cmd/extension/command.go index 8693a6c5d..cbf92de0a 100644 --- a/pkg/cmd/extension/command.go +++ b/pkg/cmd/extension/command.go @@ -38,7 +38,7 @@ func NewCmdExtension(f *cmdutil.Factory) *cobra.Command { Long: heredoc.Docf(` GitHub CLI extensions are repositories that provide additional gh commands. - The name of the extension repository must start with "gh-" and it must contain an + The name of the extension repository must start with %[1]sgh-%[1]s and it must contain an executable of the same name. All arguments passed to the %[1]sgh %[1]s invocation will be forwarded to the %[1]sgh-%[1]s executable of the extension. @@ -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 "OWNER/REPO" + second is the full name of the extension repository in %[1]sOWNER/REPO%[1]s format. The third is the extension's description. When not connected to a terminal, the ✓ character is rendered as the @@ -300,10 +300,10 @@ 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 %[1]sOWNER/REPO%[1]s 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 + To install an extension in development from the current directory, use %[1]s.%[1]s as the value of the repository argument. See the list of available extensions at . @@ -436,10 +436,10 @@ func NewCmdExtension(f *cmdutil.Factory) *cobra.Command { interface for browsing, adding, and removing gh extensions. A terminal width greater than 100 columns is recommended. - To learn how to control this interface, press ? after running to see + To learn how to control this interface, press %[1]s?%[1]s after running to see the help text. - Press q to quit. + Press %[1]sq%[1]s to quit. 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 @@ -492,14 +492,14 @@ func NewCmdExtension(f *cmdutil.Factory) *cobra.Command { &cobra.Command{ Use: "exec [args]", Short: "Execute an installed extension", - Long: heredoc.Doc(` + Long: heredoc.Docf(` Execute an extension using the short name. For example, if the extension repository is - "owner/gh-extension", you should pass "extension". You can use this command when + %[1]sowner/gh-extension%[1]s, you should pass %[1]sextension%[1]s. You can use this command when the short name conflicts with a core gh command. All arguments after the extension name will be forwarded to the executable of the extension. - `), + `, "`"), Example: heredoc.Doc(` # execute a label extension instead of the core gh label command $ gh extension exec label diff --git a/pkg/cmd/repo/clone/clone.go b/pkg/cmd/repo/clone/clone.go index b6def2edd..bac5727c8 100644 --- a/pkg/cmd/repo/clone/clone.go +++ b/pkg/cmd/repo/clone/clone.go @@ -44,14 +44,14 @@ func NewCmdClone(f *cmdutil.Factory, runF func(*CloneOptions) error) *cobra.Comm Short: "Clone a repository locally", Long: heredoc.Docf(` Clone a GitHub repository locally. Pass additional %[1]sgit clone%[1]s flags by listing - them after "--". + them after %[1]s--%[1]s. - If the "OWNER/" portion of the "OWNER/REPO" repository argument is omitted, it + If the %[1]sOWNER/%[1]s portion of the %[1]sOWNER/REPO%[1]s repository argument is omitted, it defaults to the name of the authenticating user. If the repository is a fork, its parent repository will be added as an additional - git remote called "upstream". The remote name can be configured using %[1]s--upstream-remote-name%[1]s. - The %[1]s--upstream-remote-name%[1]s option supports an "@owner" value which will name + git remote called %[1]supstream%[1]s. The remote name can be configured using %[1]s--upstream-remote-name%[1]s. + The %[1]s--upstream-remote-name%[1]s option supports an %[1]s@owner%[1]s value which will name the remote after the owner of the parent repository. If the repository is a fork, its parent repository will be set as the default remote repository. diff --git a/pkg/cmd/repo/fork/fork.go b/pkg/cmd/repo/fork/fork.go index 73fa906a6..2889c30ec 100644 --- a/pkg/cmd/repo/fork/fork.go +++ b/pkg/cmd/repo/fork/fork.go @@ -88,11 +88,11 @@ func NewCmdFork(f *cmdutil.Factory, runF func(*ForkOptions) error) *cobra.Comman With no argument, creates a fork of the current repository. Otherwise, forks the specified repository. - By default, the new fork is set to be your "origin" remote and any existing - origin remote is renamed to "upstream". To alter this behavior, you can set + By default, the new fork is set to be your %[1]sorigin%[1]s remote and any existing + origin remote is renamed to %[1]supstream%[1]s. To alter this behavior, you can set a name for the new fork's remote with %[1]s--remote-name%[1]s. - The "upstream" remote will be set as the default remote repository. + The %[1]supstream%[1]s remote will be set as the default remote repository. Additional git clone flags can be passed after %[1]s--%[1]s. `, "`"), diff --git a/pkg/cmd/root/help_topic.go b/pkg/cmd/root/help_topic.go index 537702005..152659970 100644 --- a/pkg/cmd/root/help_topic.go +++ b/pkg/cmd/root/help_topic.go @@ -34,7 +34,7 @@ var HelpTopics = []helpTopic{ 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: %[1]swinpty gh auth login%[1]s. + - Prefix invocations of gh with %[1]swinpty%[1]s, eg: %[1]swinpty gh auth login%[1]s. NOTE: this can lead to some UI bugs. `, "`"), }, @@ -61,23 +61,23 @@ var HelpTopics = []helpTopic{ %[1]sGH_BROWSER%[1]s, %[1]sBROWSER%[1]s (in order of precedence): the web browser to use for opening links. - %[1]sGH_DEBUG%[1]s: 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 %[1]sapi%[1]s to additionally log details of HTTP traffic. - %[1]sDEBUG%[1]s (deprecated): set to "1", "true", or "yes" to enable verbose output on standard + %[1]sDEBUG%[1]s (deprecated): set to %[1]s1%[1]s, %[1]strue%[1]s, or %[1]syes%[1]s to enable verbose output on standard error. %[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". + to, e.g. %[1]sless%[1]s. %[1]sGLAMOUR_STYLE%[1]s: the style to use for rendering Markdown. See %[1]sNO_COLOR%[1]s: set to any value to avoid printing ANSI escape sequences for color output. - %[1]sCLICOLOR%[1]s: set to "0" to disable printing ANSI colors in output. + %[1]sCLICOLOR%[1]s: set to %[1]s0%[1]s to disable printing ANSI colors in output. - %[1]sCLICOLOR_FORCE%[1]s: set to a value other than "0" to keep ANSI colors in output + %[1]sCLICOLOR_FORCE%[1]s: set to a value other than %[1]s0%[1]s to keep ANSI colors in output even when the output is piped. %[1]sGH_FORCE_TTY%[1]s: set to any value to force terminal-style output even when the output is diff --git a/pkg/cmd/ruleset/list/list.go b/pkg/cmd/ruleset/list/list.go index 91f5e765f..f9c8f4880 100644 --- a/pkg/cmd/ruleset/list/list.go +++ b/pkg/cmd/ruleset/list/list.go @@ -48,7 +48,7 @@ func NewCmdList(f *cmdutil.Factory, runF func(*ListOptions) error) *cobra.Comman configured for the provided organization. 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. + repository or organization should be returned. The default is %[1]strue%[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. `, "`"), diff --git a/pkg/cmd/ruleset/view/view.go b/pkg/cmd/ruleset/view/view.go index 1359b1b56..d272d273e 100644 --- a/pkg/cmd/ruleset/view/view.go +++ b/pkg/cmd/ruleset/view/view.go @@ -52,7 +52,7 @@ func NewCmdView(f *cmdutil.Factory, runF func(*ViewOptions) 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. + be returned. The default is %[1]strue%[1]s. `, "`"), Example: heredoc.Doc(` # Interactively choose a ruleset to view from all rulesets that apply to the current repository