PSBashCompletions: Bash Argument Completion in PowerShell

powershell, windows comments edit

Two things crossed my path in a relatively short period of time that got me thinking:

  1. I read Scott Hanselman’s article on dotnet CLI completion for PowerShell and I liked it a lot. I didn’t know you could have custom completions.
  2. I have been working a lot with Kubernetes and kubectl in PowerShell and wanted completion for that… but you can only get it for bash, not PowerShell.

Challenge accepted.

A lot of Google-fu and some trial-and-error later, and I have a bridge that takes a PowerShell command line, passes it to bash, manually runs the completion function in bash, and hands the set of completions back to PowerShell.

Introducing: PSBashCompletions - a PowerShell module to enable bash completions to surface in PowerShell.

I published it as a module on the PowerShell Gallery so you can install it nice and easy:

Install-Module -Name PSBashCompletions -Scope CurrentUser

(I always install to my own profile because I don’t run as admin.)

You can also go grab it right from GitHub if you want.

To use it:

  1. Make sure bash.exe is in your path. If it’s not, the module will fall back to the location of Git for Windows (assuming git.exe can be found) and try to use the packaged bash.exe there. Failing that… you’re stuck. You need bash.
  2. Locate your bash completion script. Sometimes you can export this from the command (like kubectl); other times you can download it from the project (like git when using Git for Windows).
  3. Register the completer using Register-BashArgumentCompleter. Tell the completer which command you want to complete (kubectl) and where the completion script is (C:\completions\kubectl_completions.sh).

A registration looks like:

Register-BashArgumentCompleter kubectl C:\completions\kubectl_completions.sh

After that, in PowerShell you should be able to use the command and hit tab at the end of the line to get completions.

kubectl c<TAB>

That will compete all the commands starting with ‘c’ for kubectl.

I tried to test it a bunch, but I can’t guarantee it’ll work for every completion or every workstation.

I put troubleshooting instructions in the source readme so if it’s not working there are ways to figure it out. Using the -Verbose option when calling Register-BashArgumentCompleter is the first step to seeing what’s up. If completers in PowerShell encounter any errors, the messages get swallowed. The -Verbose option will tell you the basic bash command line the completer is going to try using so you can run it and see what happens.

I do have some demo/example completions I’ve exported (for git and kubectl) so you can try it out by grabbing those if you want.

Find something wrong? I’d love a PR to fix it.

Comments