diff --git a/docs/windows-powershell-utf8.md b/docs/windows-powershell-utf8.md new file mode 100644 index 0000000..c12a01a --- /dev/null +++ b/docs/windows-powershell-utf8.md @@ -0,0 +1,53 @@ +# Windows PowerShell UTF-8 Setup + +Windows PowerShell 5.1 may read UTF-8 files without a byte order mark as the legacy Windows ANSI code page. When that happens, Unicode text such as gitmoji appears as mojibake: + +```text +🤖 +``` + +The file itself can still be valid UTF-8. The problem is usually the decoding choice made by `Get-Content`. + +## Fix for the Current User + +Add UTF-8 defaults to your Windows PowerShell profile: + +```powershell +$PSDefaultParameterValues['Get-Content:Encoding'] = 'UTF8' +$PSDefaultParameterValues['Set-Content:Encoding'] = 'UTF8' +$PSDefaultParameterValues['Add-Content:Encoding'] = 'UTF8' +$PSDefaultParameterValues['Out-File:Encoding'] = 'UTF8' + +[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new() +$OutputEncoding = [System.Text.UTF8Encoding]::new() +``` + +The profile path for Windows PowerShell is usually: + +```powershell +$PROFILE +``` + +On this machine it is: + +```text +C:\g4b\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1 +``` + +Restart PowerShell after editing the profile. + +## One-Off Command + +For a single read, pass the encoding explicitly: + +```powershell +Get-Content -Encoding UTF8 docs\workpad\specs\commit-conventions.md +``` + +## PowerShell 7 + +PowerShell 7 (`pwsh`) defaults to UTF-8 more consistently than Windows PowerShell 5.1. If available, using `pwsh` is usually the cleaner long-term fix. + +## What This Does Not Change + +Repo files such as `.gitattributes` can tell Git how to handle text normalization, but they do not force Windows PowerShell 5.1 to decode files as UTF-8. The shell profile or explicit `-Encoding UTF8` is still needed for `Get-Content`.