reliquary/docs/windows-powershell-utf8.md

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:

🤖

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:

$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:

$PROFILE

On this machine it is:

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:

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.