cli · andyfeller · Dec 1, 2023 · Nov 10, 2023 · Nov 10, 2023 · Nov 10, 2023
@@ -26,36 +26,36 @@ func actionsExplainer(cs *iostreams.ColorScheme) string {
 	header := cs.Bold("Welcome to GitHub Actions on the command line.")
 	runHeader := cs.Bold("Interacting with workflow runs")
 	workflowHeader := cs.Bold("Interacting with workflow files")
-	cacheHeader := cs.Bold("Interacting with the Actions cache")
+	cacheHeader := cs.Bold("Interacting with the GitHub Actions cache")
 
 	return heredoc.Docf(`
-			%s
+			%[2]s
 
-			GitHub CLI integrates with Actions to help you manage runs and workflows.
+			GitHub CLI integrates with GitHub Actions to help you manage runs and workflows.
 
-			%s  
+			%[3]s
 			gh run list:      List recent workflow runs  
 			gh run view:      View details for a workflow run or one of its jobs  
 			gh run watch:     Watch a workflow run while it executes  
 			gh run rerun:     Rerun a failed workflow run  
 			gh run download:  Download artifacts generated by runs
 
-			To see more help, run 'gh help run <subcommand>'
+			To see more help, run %[1]sgh help run <subcommand>%[1]s
 
-			%s  
+			%[4]s
 			gh workflow list:     List workflow files in your repository
 			gh workflow view:     View details for a workflow file  
 			gh workflow enable:   Enable a workflow file  
 			gh workflow disable:  Disable a workflow file  
 			gh workflow run:      Trigger a workflow_dispatch run for a workflow file
 
-			To see more help, run 'gh help workflow <subcommand>'
+			To see more help, run %[1]sgh help workflow <subcommand>%[1]s
 
-			%s
-			gh cache list:    List all the caches saved in Actions for a repository
-			gh cache delete:  Delete one or all saved caches in Actions for a repository
+			%[5]s
+			gh cache list:    List all the caches saved in GitHub Actions for a repository
+			gh cache delete:  Delete one or all saved caches in GitHub Actions for a repository
 
-			To see more help, run 'gh help cache <subcommand>'
+			To see more help, run %[1]sgh help cache <subcommand>%[1]s
 
-		`, header, runHeader, workflowHeader, cacheHeader)
+		`, "`", header, runHeader, workflowHeader, cacheHeader)
 }
@@ -14,11 +14,11 @@ func NewCmdAlias(f *cmdutil.Factory) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "alias <command>",
 		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)

@@ -34,7 +34,7 @@ func NewCmdImport(f *cmdutil.Factory, runF func(*ImportOptions) error) *cobra.Co
 	cmd := &cobra.Command{
 		Use:   "import [<filename> | -]",
 		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
@@ -47,12 +47,12 @@ 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 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

@@ -35,21 +35,21 @@ func NewCmdSet(f *cmdutil.Factory, runF func(*SetOptions) error) *cobra.Command
 	cmd := &cobra.Command{
 		Use:   "set <alias> <expansion>",
 		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
-			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 "-" 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 "--shell" was given, the expansion is a shell
-			expression that will be evaluated through the "sh" interpreter when the alias is
+			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.
-		`),
+		`, "`"),
 		Example: heredoc.Doc(`
 			# note: Command Prompt on Windows requires using double quotes for arguments
 			$ gh alias set pv 'pr view'

@@ -71,43 +71,43 @@ func NewCmdApi(f *cmdutil.Factory, runF func(*ApiOptions) error) *cobra.Command
 			Makes an authenticated HTTP request to the GitHub API and prints the response.
 
 			The endpoint argument should either be a path of a GitHub API v3 endpoint, or
-			"graphql" to access the GitHub API v4.
+			%[1]sgraphql%[1]s 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 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
+			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
+			The default HTTP request method is %[1]sGET%[1]s normally and %[1]sPOST%[1]s 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--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 %[1]sPOST%[1]s. To send the parameters as a %[1]sGET%[1]s 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:
 
-			- 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
-			  filename to read the value from. Pass "-" to read from standard input.
+			- 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
-			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.
 

@@ -63,13 +63,13 @@ func NewCmdLogin(f *cmdutil.Factory, runF func(*LoginOptions) error) *cobra.Comm
 			See %[1]sgh auth status%[1]s for its stored location.
 
 			Alternatively, use %[1]s--with-token%[1]s to pass in a token on standard input.
-			The minimum required scopes for the token are: "repo", "read:org".
+			The minimum required scopes for the token are: %[1]srepo%[1]s, %[1]sread:org%[1]s, and %[1]sgist%[1]s.
 
 			Alternatively, gh will use the authentication token found in environment variables.
 			This method is most suitable for "headless" use of gh such as in automation. See
 			%[1]sgh help environment%[1]s for more info.
 
-			To use gh in GitHub Actions, add %[1]sGH_TOKEN: ${{ github.token }}%[1]s to "env".
+			To use gh in GitHub Actions, add %[1]sGH_TOKEN: ${{ github.token }}%[1]s to %[1]senv%[1]s.
 		`, "`"),
 		Example: heredoc.Doc(`
 			# start interactive setup

@@ -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

@@ -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 minimum set of scopes (%[1]srepo%[1]s, %[1]sread:org%[1]s, and %[1]sgist%[1]s) 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

@@ -33,7 +33,7 @@ func NewCmdSetupGit(f *cmdutil.Factory, runF func(*SetupGitOptions) error) *cobr
 		Use:   "setup-git",
 		Short: "Setup git with GitHub CLI",
 		Long: heredoc.Docf(`
-			This command configures git to use GitHub CLI as a credential helper.
+			This command configures %[1]sgit%[1]s to use GitHub CLI as a credential helper.
 			For more information on git credential helpers please reference:
 			https://git-scm.com/docs/gitcredentials.
 

@@ -53,39 +53,39 @@ func newSSHCmd(app *App) *cobra.Command {
 	sshCmd := &cobra.Command{
 		Use:   "ssh [<flags>...] [-- <ssh-flags>...] [<command>]",
 		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 <ssh-flags>
+			1. Key specified by %[1]s-i%[1]s in %[1]s<ssh-flags>%[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/rsync/sshfs%[1]s, %[1]sgit%[1]s 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:
+			install it in your %[1]sDockerfile%[1]s or, for codespaces that use Debian-based images,
+			you can add the following to your %[1]sdevcontainer.json%[1]s:
 
-			"features": {
-				"ghcr.io/devcontainers/features/sshd:1": {
-					"version": "latest"
+				"features": {
+					"ghcr.io/devcontainers/features/sshd:1": {
+						"version": "latest"
+					}
 				}
-			}
-		`),
+		`, "`"),
 		Example: heredoc.Doc(`
 			$ gh codespace ssh
 
@@ -693,15 +693,15 @@ func newCpCmd(app *App) *cobra.Command {
 		Use:   "cp [-e] [-r] [-- [<scp flags>...]] <sources>... <dest>",
 		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,
 			if the destination is a directory.
 
 			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 dir
702D
ectory of the remote user.
 
@@ -711,8 +711,8 @@ func newCpCmd(app *App) *cobra.Command {
 			environment variables, and backticks. For security, do not use this flag with arguments
 			provided by untrusted users; see <https://lwn.net/Articles/835962/> for discussion.
 
-			By default, the 'cp' command will create a public/private ssh key pair to authenticate with 
-			the codespace inside the ~/.ssh directory.
+			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(`
 			$ gh codespace cp -e README.md 'remote:/workspaces/$RepositoryName/'