Fix PowerShell instructions for GitHub Copilot CLI

[mpusch88]

Code of Conduct

• [X] 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! 💛