Add docs for tilde expansion

reference/5.1/Microsoft.PowerShell.Core/About/about_Parsing.md

@@ -1,7 +1,7 @@
 ---
 description: Describes how PowerShell parses commands.
 Locale: en-US
-ms.date: 02/26/2024
+ms.date: 05/06/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Parsing
@@ -415,6 +415,74 @@ Arg 2 is <-->
 Arg 3 is <-c>
 ```
 
+## Tilde (~)
+
+The tilde character (`~`) has special meaning in PowerShell. When it's used
+with PowerShell commands at the beginning of a path, the tilde character is
+expanded to the user's home directory. If the tilde character is used anywhere
+else in a path, it's treated as a literal character.
+
+```powershell
+PS D:\temp> $PWD
+
+Path
+----
+D:\temp
+
+PS D:\temp> Set-Location ~
+PS C:\Users\user2> $PWD
+
+Path
+----
+C:\Users\user2
+```
+
+In this example, the **Name** parameter of the `New-Item` expects a string. The
+tilde character is treated as a literal character. To change to the newly
+created directory, you must qualify the path with the tilde character.
+
+```powershell
+PS D:\temp> Set-Location ~
+PS C:\Users\user2> New-Item -Type Directory -Name ~
+
+    Directory: C:\Users\user2
+
+Mode                 LastWriteTime         Length Name
+----                 -------------         ------ ----
+d----            5/6/2024  2:08 PM                ~
+
+PS C:\Users\user2> Set-Location ~
+PS C:\Users\user2> Set-Location .\~
+PS C:\Users\user2\~> $PWD
+
+Path
+----
+C:\Users\user2\~
+```
+
+When you use the tilde character with native commands, PowerShell passes the
+tilde as a literal character. Using the tilde in a path causes errors for
+native commands on Windows that don't support the tilde character.
+
+```powershell
+PS D:\temp> $PWD
+
+Path
+----
+D:\temp
+
+PS D:\temp> Get-Item ~\repocache.clixml
+
+    Directory: C:\Users\user2
+
+Mode                 LastWriteTime         Length Name
+----                 -------------         ------ ----
+-a---           4/29/2024  3:42 PM          88177 repocache.clixml
+
+PS D:\temp> more.com ~\repocache.clixml
+Cannot access file D:\temp\~\repocache.clixml
+```
+
 ## See also
 
 - [about_Command_Syntax][04]

reference/5.1/Microsoft.PowerShell.Core/About/about_Special_Characters.md

@@ -1,7 +1,7 @@
 ---
 description: Describes the special character sequences that control how PowerShell interprets the next characters in the sequence.
 Locale: en-US
-ms.date: 02/23/2024
+ms.date: 05/06/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_special_characters?view=powershell-5.1&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Special Characters
@@ -50,6 +50,7 @@ Special parsing tokens:
 | -------- | ------------------------------------------------------ |
 | `--`     | Treat the remaining values as arguments not parameters |
 | `--%`    | Stop parsing anything that follows                     |
+| `~`      | Tilde                                                  |
 
 ## Null (`0)
 
@@ -234,7 +235,7 @@ cmd.exe /c echo $HOME --% $HOME
 
 The output shows that the first instance of `$HOME` is interpreted by
 PowerShell so that the value of the variable is passed to `cmd`. The second
-instance of `$HOME` comes after the stop-parsing token, so it is passed as a
+instance of `$HOME` comes after the stop-parsing token, so it's passed as a
 literal string.
 
 ```Output
@@ -243,13 +244,22 @@ C:\Users\username  $HOME
 
 For more information about the stop-parsing token, see [about_Parsing][02].
 
+## Tilde (~)
+
+The tilde character (`~`) has special meaning in PowerShell. When it's used
+with PowerShell commands at the beginning of a path, PowerShell expands the
+tilde character to the user's home directory. If you use the tilde character
+anywhere else in a path, it's treated as a literal character.
+
+For more information about the stop-parsing token, see [about_Parsing][03].
+
 ## See also
 
-- [about_Quoting_Rules][03]
+- [about_Quoting_Rules][04]
 
 <!-- link references -->
 [01]: about_Parsing.md#line-continuation
 [02]: about_Parsing.md#the-stop-parsing-token
-[03]: about_Quoting_Rules.md
-[04]: https://wikipedia.org/wiki/ANSI_escape_code
+[03]: about_Parsing.md#tilde-~
+[04]: about_Quoting_Rules.md
 [05]: https://www.microsoft.com/p/windows-terminal/9n0dx20hk701

reference/7.2/Microsoft.PowerShell.Core/About/about_Parsing.md

@@ -1,7 +1,7 @@
 ---
 description: Describes how PowerShell parses commands.
 Locale: en-US
-ms.date: 02/26/2024
+ms.date: 05/06/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.2&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Parsing
@@ -467,6 +467,74 @@ Arg 2 is <-->
 Arg 3 is <-c>
 ```
 
+## Tilde (~)
+
+The tilde character (`~`) has special meaning in PowerShell. When it's used
+with PowerShell commands at the beginning of a path, the tilde character is
+expanded to the user's home directory. If the tilde character is used anywhere
+else in a path, it's treated as a literal character.
+
+```powershell
+PS D:\temp> $PWD
+
+Path
+----
+D:\temp
+
+PS D:\temp> Set-Location ~
+PS C:\Users\user2> $PWD
+
+Path
+----
+C:\Users\user2
+```
+
+In this example, the **Name** parameter of the `New-Item` expects a string. The
+tilde character is treated as a literal character. To change to the newly
+created directory, you must qualify the path with the tilde character.
+
+```powershell
+PS D:\temp> Set-Location ~
+PS C:\Users\user2> New-Item -Type Directory -Name ~
+
+    Directory: C:\Users\user2
+
+Mode                 LastWriteTime         Length Name
+----                 -------------         ------ ----
+d----            5/6/2024  2:08 PM                ~
+
+PS C:\Users\user2> Set-Location ~
+PS C:\Users\user2> Set-Location .\~
+PS C:\Users\user2\~> $PWD
+
+Path
+----
+C:\Users\user2\~
+```
+
+When you use the tilde character with native commands, PowerShell passes the
+tilde as a literal character. Using the tilde in a path causes errors for
+native commands on Windows that don't support the tilde character.
+
+```powershell
+PS D:\temp> $PWD
+
+Path
+----
+D:\temp
+
+PS D:\temp> Get-Item ~\repocache.clixml
+
+    Directory: C:\Users\user2
+
+Mode                 LastWriteTime         Length Name
+----                 -------------         ------ ----
+-a---           4/29/2024  3:42 PM          88177 repocache.clixml
+
+PS D:\temp> more.com ~\repocache.clixml
+Cannot access file D:\temp\~\repocache.clixml
+```
+
 ## See also
 
 - [about_Command_Syntax][05]

reference/7.2/Microsoft.PowerShell.Core/About/about_Special_Characters.md

@@ -1,7 +1,7 @@
 ---
 description: Describes the special character sequences that control how PowerShell interprets the next characters in the sequence.
 Locale: en-US
-ms.date: 02/23/2024
+ms.date: 05/06/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_special_characters?view=powershell-7.2&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Special Characters
@@ -52,6 +52,7 @@ Special parsing tokens:
 | -------- | ------------------------------------------------------ |
 | `--`     | Treat the remaining values as arguments not parameters |
 | `--%`    | Stop parsing anything that follows                     |
+| `~`      | Tilde                                                  |
 
 ## Null (`0)
 
@@ -101,7 +102,7 @@ virtual terminal sequences. You can check the boolean value of
 supported.
 
 For more information about ANSI escape sequences, see the
-[ANSI escape code][04] article in Wikipedia.
+[ANSI escape code][05] article in Wikipedia.
 
 The following example outputs text with a green foreground color.
 
@@ -212,7 +213,7 @@ character with no extra spacing added.
 There is a vertical tab♂between the words.
 ```
 
-The [Windows Terminal][05] renders the vertical tab character as a carriage
+The [Windows Terminal][06] renders the vertical tab character as a carriage
 return and line feed. The rest of the output is printed at the beginning of the
 next line.
 
@@ -291,13 +292,23 @@ C:\Users\username  $HOME
 
 For more information about the stop-parsing token, see [about_Parsing][02].
 
+## Tilde (~)
+
+The tilde character (`~`) has special meaning in PowerShell. When it's used
+with PowerShell commands at the beginning of a path, PowerShell expands the
+tilde character to the user's home directory. If you use the tilde character
+anywhere else in a path, it's treated as a literal character.
+
+For more information about the stop-parsing token, see [about_Parsing][03].
+
 ## See also
 
-- [about_Quoting_Rules][03]
+- [about_Quoting_Rules][04]
 
 <!-- link references -->
 [01]: about_Parsing.md#line-continuation
 [02]: about_Parsing.md#the-stop-parsing-token
-[03]: about_Quoting_Rules.md
-[04]: https://wikipedia.org/wiki/ANSI_escape_code
-[05]: https://www.microsoft.com/p/windows-terminal/9n0dx20hk701
+[03]: about_Parsing.md#tilde-~
+[04]: about_Quoting_Rules.md
+[05]: https://wikipedia.org/wiki/ANSI_escape_code
+[06]: https://www.microsoft.com/p/windows-terminal/9n0dx20hk701

reference/7.3/Microsoft.PowerShell.Core/About/about_Parsing.md

@@ -1,7 +1,7 @@
 ---
 description: Describes how PowerShell parses commands.
 Locale: en-US
-ms.date: 02/26/2024
+ms.date: 05/06/2024
 online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.3&WT.mc_id=ps-gethelp
 schema: 2.0.0
 title: about Parsing
@@ -465,6 +465,74 @@ Arg 2 is <-->
 Arg 3 is <-c>
 ```
 
+## Tilde (~)
+
+The tilde character (`~`) has special meaning in PowerShell. When it's used
+with PowerShell commands at the beginning of a path, the tilde character is
+expanded to the user's home directory. If the tilde character is used anywhere
+else in a path, it's treated as a literal character.
+
+```powershell
+PS D:\temp> $PWD
+
+Path
+----
+D:\temp
+
+PS D:\temp> Set-Location ~
+PS C:\Users\user2> $PWD
+
+Path
+----
+C:\Users\user2
+```
+
+In this example, the **Name** parameter of the `New-Item` expects a string. The
+tilde character is treated as a literal character. To change to the newly
+created directory, you must qualify the path with the tilde character.
+
+```powershell
+PS D:\temp> Set-Location ~
+PS C:\Users\user2> New-Item -Type Directory -Name ~
+
+    Directory: C:\Users\user2
+
+Mode                 LastWriteTime         Length Name
+----                 -------------         ------ ----
+d----            5/6/2024  2:08 PM                ~
+
+PS C:\Users\user2> Set-Location ~
+PS C:\Users\user2> Set-Location .\~
+PS C:\Users\user2\~> $PWD
+
+Path
+----
+C:\Users\user2\~
+```
+
+When you use the tilde character with native commands, PowerShell passes the
+tilde as a literal character. Using the tilde in a path causes errors for
+native commands on Windows that don't support the tilde character.
+
+```powershell
+PS D:\temp> $PWD
+
+Path
+----
+D:\temp
+
+PS D:\temp> Get-Item ~\repocache.clixml
+
+    Directory: C:\Users\user2
+
+Mode                 LastWriteTime         Length Name
+----                 -------------         ------ ----
+-a---           4/29/2024  3:42 PM          88177 repocache.clixml
+
+PS D:\temp> more.com ~\repocache.clixml
+Cannot access file D:\temp\~\repocache.clixml
+```
+
 ## See also
 
 - [about_Command_Syntax][04]