docs(git): steer posh-git users to source: pwsh, add FAQ

resolves #7718

Entire-Checkpoint: 631ff72e482a

website/docs/faq.mdx

@@ -354,6 +354,21 @@ oh-my-posh config migrate glyphs --write
 This will update your configuration file to use the new glyph locations. Do know they might look different, as they also
 updated the icons themselves. A backup of the current config can be found in the same location with a `.bak` extension.
 
+## My posh-git prompt string doesn't render anymore
+
+You're relying on the `POSH_GIT_STRING` environment variable, set via `Write-GitStatus` and shown through a
+[text segment][text], and instead of your git status you now see raw escape codes like `[93m[[39m...`.
+
+`POSH_GIT_STRING` carries ANSI escape sequences, and Oh My Posh strips ANSI escape sequences from environment
+variable values before rendering them, so the string can no longer display as intended. This isn't a
+regression to revert, environment variables aren't meant to carry raw ANSI, and stripping them closes a
+class of prompt-injection issues.
+
+Migrate to the git segment's `source: pwsh` option instead. It fetches the same data from the [posh-git][poshgit]
+module, but through the segment's regular template properties (`.Staging`, `.Working`, `.BranchStatus`, ...)
+rather than a pre-rendered, ANSI-laden string, so nothing gets stripped. See the [posh-git section][git-poshgit]
+of the git segment docs for a sample template that reproduces posh-git's default output.
+
 ## Xonsh: Right prompt jumps to bottom of the screen
 
 This is a known problem with Xonsh. The issue is tracked [here][xonsh-issue].
@@ -380,3 +395,6 @@ This is a known problem with Xonsh. The issue is tracked [here][xonsh-issue].
 [xonsh-issue]: https://github.com/xonsh/xonsh/issues/3810
 [zsh-init]: https://github.com/JanDeDobbeleer/oh-my-posh/discussions/3462#discussioncomment-5155790
 [fish-mode-prompt]: https://fishshell.com/docs/current/cmds/fish_mode_prompt.html#example
+[text]: /docs/segments/system/text
+[poshgit]: https://github.com/dahlbyk/posh-git
+[git-poshgit]: /docs/segments/scm/git#posh-git

website/docs/segments/scm/git.mdx

@@ -217,26 +217,27 @@ As these are arrays of strings, you can join them using the `join` function:
 
 ## posh-git
 
-If you want to display the default [posh-git][poshgit] output, **do not** use this segment
-but add the following snippet after initializing Oh My Posh in your `$PROFILE`:
-
-```powershell
-function Set-PoshGitStatus {
-    $global:GitStatus = Get-GitStatus
-    $env:POSH_GIT_STRING = Write-GitStatus -Status $global:GitStatus
-}
-New-Alias -Name 'Set-PoshContext' -Value 'Set-PoshGitStatus' -Scope Global -Force
-```
-
-You can then use the `POSH_GIT_STRING` environment variable in a [text segment][text]:
+Use the `source: pwsh` option to fetch status information from the [posh-git][poshgit] PowerShell
+module instead of the `git` CLI. This populates the same template properties as above, so you're
+not limited to what `Write-GitStatus` prints, and nothing relies on ANSI escape sequences.
 
 <Config
   data={{
+    type: "git",
+    style: "plain",
     template:
-      "{{ if .Env.POSH_GIT_STRING }} {{ .Env.POSH_GIT_STRING }} {{ end }}",
+      "[{{ .HEAD }}{{ if .BranchStatus }} {{ .BranchStatus }}{{ end }}{{ if .Staging.Changed }} +{{ .Staging.Added }} ~{{ .Staging.Modified }} -{{ .Staging.Deleted }}{{ if gt .Staging.Unmerged 0 }} !{{ .Staging.Unmerged }}{{ end }}{{ end }}{{ if and .Staging.Changed .Working.Changed }} |{{ end }}{{ if .Working.Changed }} +{{ add .Working.Added .Working.Untracked }} ~{{ .Working.Modified }} -{{ .Working.Deleted }}{{ if gt .Working.Unmerged 0 }} !{{ .Working.Unmerged }}{{ end }}{{ end }}{{ if .Working.Changed }} !{{ else if .Staging.Changed }} ~{{ end }}]",
+    options: {
+      fetch_status: true,
+      source: "pwsh",
+    },
   }}
 />
 
+The template above reproduces posh-git's default `[branch status | staged changes | working changes]` format,
+counting untracked files as added in the working tree, the same way posh-git does. Adjust icons, order, or
+gating to taste, it's a regular [template][templates] now.
+
 [git]: https://git-scm.com/
 [poshgit]: https://github.com/dahlbyk/posh-git
 [templates]: /docs/configuration/templates
@@ -247,3 +248,4 @@ You can then use the `POSH_GIT_STRING` environment variable in a [text segment][
 [text]: /docs/segments/system/text
 [exclude_folders]: /docs/configuration/segment#include--exclude-folders
 [Jujutsu]: https://www.jj-vcs.dev/
+[faq-posh-git]: /docs/faq#my-posh-git-prompt-string-doesnt-render-anymore