Fix PowerShell instructions for GitHub Copilot CLI

[mpusch88]

Code of Conduct

• I have read and agree to the GitHub Docs project's Code of Conduct

What article on docs.github.com is affected?

https://docs.github.com/en/copilot/github-copilot-in-the-cli/using-github-copilot-in-the-cli

What part(s) of the article would you like to see updated?

Currently these instructions do not clarify which versions of PowerShell the premade Copilot aliases are compatible with - it looks like the output of the gh copilot alias command only works for PowerShell 7+, not Windows PowerShell.

It seems like it would make sense to do one of the following:

• Rewrite the output of the gh copilot alias -- pwsh command
• Add a gh copilot alias -- powershell command
• Explain in the documentation that this only works for PowerShell 7+.

The expected outcome of this is that it would help people avoid confusion and annoyance.

Additional information

It's documentation - it is always reproducible, and everyone is effected.

[mklement0]

The generated function code can easily be made Windows PowerShell-compatible, so I think the best solution is to accept gh copilot alias -- powershell simply as an alias of gh copilot alias -- pwsh and emit code that works in both PowerShell editions:

• The only reason the currently generated code doesn't work is the use of PS 7+-only clean blocks.

• Using begin, process, end and clean blocks isn't actually necessary, given that the functions don't accept pipeline input, so the following cross-edition reformulation does away with them, and uses try { ... } finally { ... } for cleanup:

#  These functions work in both Windows PowerShell and PowerShell (Core) 7+
function ghcs {
	# Debug support provided by common PowerShell function parameters, which is natively aliased as -d or -db
	# https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_commonparameters?view=powershell-7.4#-debug
	param(
		[ValidateSet('gh', 'git', 'shell')]
		[Alias('t')]
		[String]$Target = 'shell',

		[Parameter(Position = 0, ValueFromRemainingArguments)]
		[string]$Prompt
	)
	# Create temporary file to store potential command user wants to execute when exiting
	$executeCommandFile = New-TemporaryFile

	# Store original value of GH_DEBUG environment variable
	$envGhDebug = $Env:GH_DEBUG

	if ($PSBoundParameters['Debug']) {
		$Env:GH_DEBUG = 'api'
	}

	try {
		gh copilot suggest -t $Target -s "$executeCommandFile" $Prompt

		# Execute command contained within temporary file if it is not empty
		if ($executeCommandFile.Length -gt 0) {
			# Extract command to execute from temporary file
			$executeCommand = (Get-Content -Path $executeCommandFile -Raw).Trim()

			# Insert command into PowerShell up/down arrow key history
			[Microsoft.PowerShell.PSConsoleReadLine]::AddToHistory($executeCommand)

			# Insert command into PowerShell history
			$now = Get-Date
			$executeCommandHistoryItem = [PSCustomObject]@{
				CommandLine        = $executeCommand
				ExecutionStatus    = [Management.Automation.Runspaces.PipelineState]::NotStarted
				StartExecutionTime = $now
				EndExecutionTime   = $now.AddSeconds(1)
			}
			Add-History -InputObject $executeCommandHistoryItem

			# Execute command
			Write-Host "`n"
			Invoke-Expression $executeCommand
      
		}
	}
	finally {
		# Clean up temporary file used to store potential command user wants to execute when exiting
		Remove-Item -Path $executeCommandFile
		# Restore GH_DEBUG environment variable to its original value
		$Env:GH_DEBUG = $envGhDebug
	}
}

function ghce {
	# Debug support provided by common PowerShell function parameters, which is natively aliased as -d or -db
	# https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_commonparameters?view=powershell-7.4#-debug
	param(
		[Parameter(Position = 0, ValueFromRemainingArguments)]
		[string[]]$Prompt
	)
	# Store original value of GH_DEBUG environment variable
	$envGhDebug = $Env:GH_DEBUG
	if ($PSBoundParameters['Debug']) {
		$Env:GH_DEBUG = 'api'
	}

	try {
		gh copilot explain $Prompt
	}
	finally {
		# Restore GH_DEBUG environment variable to its original value
		$Env:GH_DEBUG = $envGhDebug
	}

}

[nguyenalex836]

@mpusch88 Thank you for opening this PR, and thank you @mklement0 for the added perspective! ✨ Our team will provide feedback regarding the best next steps for this issue - thanks for your patience! 💛

[hubwriter]

@mpusch88 and @mklement0 - thanks for raising and commenting on this issue.

Please clarify what change needs to be made to the documentation.

[mpusch88]

"It seems like it would make sense to do one of the following:

Rewrite the output of the gh copilot alias -- pwsh command
Add a gh copilot alias -- powershell command
Explain in the documentation that this only works for PowerShell 7+."

The winner is clearly "Rewrite the output of the gh copilot alias -- pwsh command". I don't have time to do that right now.

[hubwriter]

I've marked this issue help-wanted. If anyone reading this would like to raise a pull request to update the docs as suggested above that would be great.

For information about contributing to the docs see:
https://docs.github.com/en/contributing