From 7a55ba18afd1fd5c9f41ef276f32e5afcb13228a Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 6 May 2024 15:25:09 -0500 Subject: [PATCH] Add docs for tilde expansion --- .../About/about_Parsing.md | 70 ++++++++++++- .../About/about_Special_Characters.md | 20 +++- .../About/about_Parsing.md | 70 ++++++++++++- .../About/about_Special_Characters.md | 25 +++-- .../About/about_Parsing.md | 70 ++++++++++++- .../About/about_Special_Characters.md | 25 +++-- .../About/about_Parsing.md | 70 ++++++++++++- .../About/about_Special_Characters.md | 25 +++-- .../About/about_Parsing.md | 98 ++++++++++++++++--- .../About/about_Special_Characters.md | 25 +++-- 10 files changed, 448 insertions(+), 50 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Parsing.md index da2b28e1b5ca..679f50f08792 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/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] diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Special_Characters.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Special_Characters.md index e88265be6a0d..7e9f90c03f27 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Special_Characters.md +++ b/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] [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 diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Parsing.md index 693c6dfc4670..9ac0e3cc418f 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/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] diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Special_Characters.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Special_Characters.md index 9d648060f4a8..4c5e5f29fb91 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Special_Characters.md +++ b/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] [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 diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Parsing.md index 5a45aabf52b3..7a7a05136541 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/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] diff --git a/reference/7.3/Microsoft.PowerShell.Core/About/about_Special_Characters.md b/reference/7.3/Microsoft.PowerShell.Core/About/about_Special_Characters.md index 9b4414133c14..04c0fac44ebf 100644 --- a/reference/7.3/Microsoft.PowerShell.Core/About/about_Special_Characters.md +++ b/reference/7.3/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.3&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] [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 diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Parsing.md index 0b7fd5254d50..e6417d5d95d6 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/reference/7.4/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.4&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] diff --git a/reference/7.4/Microsoft.PowerShell.Core/About/about_Special_Characters.md b/reference/7.4/Microsoft.PowerShell.Core/About/about_Special_Characters.md index aa10b6870c3c..5178b37d6067 100644 --- a/reference/7.4/Microsoft.PowerShell.Core/About/about_Special_Characters.md +++ b/reference/7.4/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.4&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] [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 diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Parsing.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Parsing.md index ddc2a3af8092..2a5f87747598 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Parsing.md +++ b/reference/7.5/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.5&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Parsing @@ -128,13 +128,13 @@ uses one of the following syntaxes: literal `@` with `()` starting a new argument that's an expression. - Everything else is treated as an expandable string, except metacharacters - that still need escaping. See [Handling special characters][02]. + that still need escaping. See [Handling special characters][03]. - The argument-mode metacharacters (characters with special syntactic meaning) are: `` ' " ` , ; ( ) { } | & < > @ #``. Of these, `< > @ #` are only special at the start of a token. - The stop-parsing token (`--%`) changes the interpretation of all remaining - arguments. For more information, see the [stop-parsing token][03] section + arguments. For more information, see the [stop-parsing token][04] section below. ### Examples @@ -331,7 +331,7 @@ Some native commands expect arguments that contain quote characters. PowerShell > The new behavior is a **breaking change** from the Window PowerShell 5.1 > behavior. This may break scripts and automation that work around the various > issues when invoking native applications. Use the stop-parsing token (`--%`) -> or the [`Start-Process`][06] cmdlet to avoid the native argument passing when +> or the [`Start-Process`][07] cmdlet to avoid the native argument passing when > needed. The new `$PSNativeCommandArgumentPassing` preference variable controls this @@ -358,7 +358,7 @@ If the `$PSNativeCommandArgumentPassing` is set to either `Legacy` or > [!NOTE] > The following examples use the `TestExe.exe` tool. You can build `TestExe` -> from the source code. See [TestExe][05] in the PowerShell source repository. +> from the source code. See [TestExe][06] in the PowerShell source repository. New behaviors made available by this change: @@ -413,7 +413,7 @@ TestExe -echoargs --% """%ProgramFiles(x86)%\Microsoft\\"" PowerShell 7.3 also added the ability to trace parameter binding for native commands. For more information, see -[Trace-Command][07]. +[Trace-Command][08]. ## Passing arguments to PowerShell commands @@ -465,15 +465,87 @@ 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, 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. + +```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\~ +``` + +PowerShell 7.5-preview.2 add an experimental feature to expand the tilde to the +user's home directory for native commands. For more information, see the +`PSNativeWindowsTildeExpansion` feature in +[Using Experimental Features in PowerShell][02]. + +The expanded string is passed to the native command. By expanding the tilde, +PowerShell prevents error for native commands on Windows that don't support the +tilde character. You can see the resulting string by tracing parameter binding +using `Trace-Command`. + +```powershell +Trace-Command -Name ParameterBinding -Expression { + findstr /c:"foo" ~\repocache.clixml +} -PSHost +``` + +```Output +DEBUG: 2024-05-06 15:13:46.8268 ParameterBinding Information: 0 : BIND NAMED native application line args [C:\Windows\system32\findstr.exe] +DEBUG: 2024-05-06 15:13:46.8270 ParameterBinding Information: 0 : BIND cmd line arg [/c:foo] to position [0] +DEBUG: 2024-05-06 15:13:46.8271 ParameterBinding Information: 0 : BIND cmd line arg [C:\Users\user2\repocache.clixml] to position [1] +DEBUG: 2024-05-06 15:13:46.8322 ParameterBinding Information: 0 : CALLING BeginProcessing +``` + +Notice that `~\repocache.clixml` was expanded to +`C:\Users\user2\repocache.clixml`. + ## See also -- [about_Command_Syntax][04] +- [about_Command_Syntax][05] [01]: /dotnet/api/system.diagnostics.processstartinfo.argumentlist -[02]: #handling-special-characters -[03]: #the-stop-parsing-token -[04]: about_Command_Syntax.md -[05]: https://github.com/PowerShell/PowerShell/blob/master/test/tools/TestExe/TestExe.cs -[06]: xref:Microsoft.PowerShell.Management.Start-Process -[07]: xref:Microsoft.PowerShell.Utility.Trace-Command +[02]: /powershell/scripting/learn/experimental-features#psnativewindowstildeexpansion +[03]: #handling-special-characters +[04]: #the-stop-parsing-token +[05]: about_Command_Syntax.md +[06]: https://github.com/PowerShell/PowerShell/blob/master/test/tools/TestExe/TestExe.cs +[07]: xref:Microsoft.PowerShell.Management.Start-Process +[08]: xref:Microsoft.PowerShell.Utility.Trace-Command diff --git a/reference/7.5/Microsoft.PowerShell.Core/About/about_Special_Characters.md b/reference/7.5/Microsoft.PowerShell.Core/About/about_Special_Characters.md index 415dfbf7b736..b3767a2851ba 100644 --- a/reference/7.5/Microsoft.PowerShell.Core/About/about_Special_Characters.md +++ b/reference/7.5/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.5&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] [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