At the end of this section you will have installed all required features for working with Git and OpenSSH in PowerShell with password protected SSH Keys and no password re-prompts!
There are a couple of optional extras that also beautify the prompt (in a useful way) and extend the command line history capabilities (also a massively useful if you spend a lot of time in the shell).
This document is split into sections that act as a work flow from top to bottom. The required features are, well, required! Everything else is optional but comes highly recommended.
If you follow through from top to bottom then you will end up with everything in working order at the end.
If you haven't already got PowerShell Package Management installed then you will need to run the following command to use Microsoft PowerShell gallery. Or one of many other methods, Chocolatey, WinGet, and so on.
Remember you will need an Administrative PowerShell for all installations.
powershell.exe -NoLogo -NoProfile -Command '[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12; Install-Module -Name PackageManagement -Force -MinimumVersion 1.4.6 -Scope CurrentUser -AllowClobber -Repository PSGallery'
The included PowerShell profile and all scripts have been tested and will all work correctly with the specified versions.
It is always advisable to move to latest release versions if available, however from time to time there have been breaking changes e.g. oh-my-posh changed the name of the theme commandlet recently.
The only required feature is posh-git as this enables better git support within PowerShell and we don't want to reinvent the wheel.
Install-Module posh-git -RequiredVersion 0.7.3
These features optionally improve working with PowerShell.
A prompt theme engine for any shell. This isn't essential, however you will gain information about the status of git and get generally useful visual cues on the prompt.
See oh-my-posh on github.
Install-Module oh-my-posh -RequiredVersion 2.0.492
PSReadLine takes history to a whole new level with Predictive IntelliSense in PowerShell.
PSReadLine is my recommended command line history management tooling and if you use ctrl-r
to back-reference previous commands then you will love PSReadLine. However please note it does get deeply integrated into PowerShell and isn't so easy to fix or remove if it goes wrong. You can set options to customize or turn it off however.
I recommend reading PSReadLine Introduction.
Install-Module PSReadLine -RequiredVersion 2.2.2
The following commands install the Microsoft OpenSSH variant for better Windows PowerShell integrations and bring the following benefits:
- Enables ssh-agent service at Windows startup for hassle free continuous use
- Can add your ssh keys using ssh-add
- Can password protect the ssh private key files without having to enter your password every time ssh makes a server side connection, e.g. when using Git via SSH!
Add the Microsoft OpenSSH feature to Windows to enable better ssh-agent integration with PowerShell so that you can password protect your ssh keys.
Add-WindowsCapability -Online -Name OpenSSH.Client
Once installed the ssh-agent service is disabled by default and you need to enable and start the service in order to work with the agent in the background.
Get-Service -Name ssh-agent | Set-Service -StartupType AutomaticDelayedStart
Add ssh private keys and use password protected identities without having to (re-)enter your password for every server command git makes.
Note: you will be prompted for your ssh private key password to add the new identity.
First we must tell Git to use the Windows OpenSSH Agent instead of the default. I recommend adding this to the powershell $profile
so you don't have to do this for each new shell instance. This is already done in the example profile provided in the pwsh directory.
# *** DONT'T SKIP THIS!!! *** #
$env:GIT_SSH = $((Get-Command -Name ssh).Source)
# *** DONT'T SKIP THIS!!! *** #
Next add your private key to the agent key ring.
ssh-add <path_to_your_private_ssh_key>
List set of managed identities, you should see the identity you just added.
ssh-add -l
Once configured you can now issue git commands such as git pull
without a password re-prompt!
If you want these changes every time you start a new PowerShell session you can modify your $Profile
.
You can either create your own or just take mine: copy the file or its contents: Microsoft.PowerShell_profile.ps1 into your $profile
.
There are a couple of settings in the top section labeled # environment
$promptTheme = 'paradox' # oh my posh theme choice
$SourcePath = (Resolve-Path '~/src').Path # your source code path, example is: "C:\Users\[your username]\src"
$env:path += ";$($env:SystemDrive)\local\bin" # your approved custom local tools to include on the path here
$env:GIT_SSH = $((Get-Command -Name ssh).Source) # use windows openssh ssh-agent
$predictionViewStyle = 'ListView' # InlineView might feel more natural at first!
$predictionSource = 'History' # All commands History
$promptTheme
defaults to my choice paradox
but there are plenty of oh-my-posh choices if you'd prefer something else just update this here.
$SourcePath
should be updated to your git source location. Or use my preferred path: ~/src
in your user profile. Just make a directory here if you don't have one and use this to house your source. This has the added benefit of encapsulation within your user space in Windows for added directory permissions.
c:\local\bin
- I usually put any command line exe tools like system internals etc. here so that they are automatically on the path. If you don't want this just remove it.
$env:GIT_SSH
- if you decide to get rid of everything else from your $profile
just remember this essential line of code that instructs Git to use Windows OpenSSH and not any other version!
$predictionViewStyle
this is the history view mode. InlineView looks like a standard prompt with a ghosted closest match from history you can auto complete with right arrow key. The ListView shows a selection of closest matches and you can scroll through the list up/down arrow keys.
$predictionSource
this is a sensible default that builds history as you type it. Other options enable a pre-determined set of options etc. best read the instructions.
If you made it this far, well done, you now have a much more functional experience within PowerShell.
So the obvious question... Why don't I put all of this in a script and automate the whole set-up. Well I'm glad you asked and I might just do that, however for now the shell is such an integrated part of peoples work-flows and very problematic if it goes wrong. By doing this step by step you have a choice as to what is integrated into your shell and what is not. In addition you get to understand the process along the way, for not too much effort, you get a good reward and know what parts are doing what for you :)