From 3704e2d46382822ca44198d9fef600d2e71d9b8f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Gabor=20K=C3=B6rber?= <gab@g4b.org>
Date: Sat, 30 May 2026 15:23:52 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20Document=20Windows=20PowerShell?=
 =?UTF-8?q?=20UTF-8=20setup?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/windows-powershell-utf8.md | 53 +++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)
 create mode 100644 docs/windows-powershell-utf8.md

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`.