Skip to content

Commit 93521dc

Browse files
sdwheelersdwheeler
authored
Add docs for tilde expansion (#11073)
* Add docs for tilde expansion * fix bookmark
1 parent c409af2 commit 93521dc

10 files changed

Lines changed: 448 additions & 50 deletions

File tree

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

Lines changed: 69 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
description: Describes how PowerShell parses commands.
33
Locale: en-US
4-
ms.date: 02/26/2024
4+
ms.date: 05/06/2024
55
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-5.1&WT.mc_id=ps-gethelp
66
schema: 2.0.0
77
title: about Parsing
@@ -415,6 +415,74 @@ Arg 2 is <-->
415415
Arg 3 is <-c>
416416
```
417417

418+
## Tilde (~)
419+
420+
The tilde character (`~`) has special meaning in PowerShell. When it's used
421+
with PowerShell commands at the beginning of a path, the tilde character is
422+
expanded to the user's home directory. If the tilde character is used anywhere
423+
else in a path, it's treated as a literal character.
424+
425+
```powershell
426+
PS D:\temp> $PWD
427+
428+
Path
429+
----
430+
D:\temp
431+
432+
PS D:\temp> Set-Location ~
433+
PS C:\Users\user2> $PWD
434+
435+
Path
436+
----
437+
C:\Users\user2
438+
```
439+
440+
In this example, the **Name** parameter of the `New-Item` expects a string. The
441+
tilde character is treated as a literal character. To change to the newly
442+
created directory, you must qualify the path with the tilde character.
443+
444+
```powershell
445+
PS D:\temp> Set-Location ~
446+
PS C:\Users\user2> New-Item -Type Directory -Name ~
447+
448+
Directory: C:\Users\user2
449+
450+
Mode LastWriteTime Length Name
451+
---- ------------- ------ ----
452+
d---- 5/6/2024 2:08 PM ~
453+
454+
PS C:\Users\user2> Set-Location ~
455+
PS C:\Users\user2> Set-Location .\~
456+
PS C:\Users\user2\~> $PWD
457+
458+
Path
459+
----
460+
C:\Users\user2\~
461+
```
462+
463+
When you use the tilde character with native commands, PowerShell passes the
464+
tilde as a literal character. Using the tilde in a path causes errors for
465+
native commands on Windows that don't support the tilde character.
466+
467+
```powershell
468+
PS D:\temp> $PWD
469+
470+
Path
471+
----
472+
D:\temp
473+
474+
PS D:\temp> Get-Item ~\repocache.clixml
475+
476+
Directory: C:\Users\user2
477+
478+
Mode LastWriteTime Length Name
479+
---- ------------- ------ ----
480+
-a--- 4/29/2024 3:42 PM 88177 repocache.clixml
481+
482+
PS D:\temp> more.com ~\repocache.clixml
483+
Cannot access file D:\temp\~\repocache.clixml
484+
```
485+
418486
## See also
419487

420488
- [about_Command_Syntax][04]

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

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
description: Describes the special character sequences that control how PowerShell interprets the next characters in the sequence.
33
Locale: en-US
4-
ms.date: 02/23/2024
4+
ms.date: 05/06/2024
55
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_special_characters?view=powershell-5.1&WT.mc_id=ps-gethelp
66
schema: 2.0.0
77
title: about Special Characters
@@ -50,6 +50,7 @@ Special parsing tokens:
5050
| -------- | ------------------------------------------------------ |
5151
| `--` | Treat the remaining values as arguments not parameters |
5252
| `--%` | Stop parsing anything that follows |
53+
| `~` | Tilde |
5354

5455
## Null (`0)
5556

@@ -234,7 +235,7 @@ cmd.exe /c echo $HOME --% $HOME
234235

235236
The output shows that the first instance of `$HOME` is interpreted by
236237
PowerShell so that the value of the variable is passed to `cmd`. The second
237-
instance of `$HOME` comes after the stop-parsing token, so it is passed as a
238+
instance of `$HOME` comes after the stop-parsing token, so it's passed as a
238239
literal string.
239240

240241
```Output
@@ -243,13 +244,22 @@ C:\Users\username $HOME
243244

244245
For more information about the stop-parsing token, see [about_Parsing][02].
245246

247+
## Tilde (~)
248+
249+
The tilde character (`~`) has special meaning in PowerShell. When it's used
250+
with PowerShell commands at the beginning of a path, PowerShell expands the
251+
tilde character to the user's home directory. If you use the tilde character
252+
anywhere else in a path, it's treated as a literal character.
253+
254+
For more information about the stop-parsing token, see [about_Parsing][03].
255+
246256
## See also
247257

248-
- [about_Quoting_Rules][03]
258+
- [about_Quoting_Rules][04]
249259

250260
<!-- link references -->
251261
[01]: about_Parsing.md#line-continuation
252262
[02]: about_Parsing.md#the-stop-parsing-token
253-
[03]: about_Quoting_Rules.md
254-
[04]: https://wikipedia.org/wiki/ANSI_escape_code
263+
[03]: about_Parsing.md#tilde-
264+
[04]: about_Quoting_Rules.md
255265
[05]: https://www.microsoft.com/p/windows-terminal/9n0dx20hk701

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

Lines changed: 69 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
description: Describes how PowerShell parses commands.
33
Locale: en-US
4-
ms.date: 02/26/2024
4+
ms.date: 05/06/2024
55
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.2&WT.mc_id=ps-gethelp
66
schema: 2.0.0
77
title: about Parsing
@@ -467,6 +467,74 @@ Arg 2 is <-->
467467
Arg 3 is <-c>
468468
```
469469

470+
## Tilde (~)
471+
472+
The tilde character (`~`) has special meaning in PowerShell. When it's used
473+
with PowerShell commands at the beginning of a path, the tilde character is
474+
expanded to the user's home directory. If the tilde character is used anywhere
475+
else in a path, it's treated as a literal character.
476+
477+
```powershell
478+
PS D:\temp> $PWD
479+
480+
Path
481+
----
482+
D:\temp
483+
484+
PS D:\temp> Set-Location ~
485+
PS C:\Users\user2> $PWD
486+
487+
Path
488+
----
489+
C:\Users\user2
490+
```
491+
492+
In this example, the **Name** parameter of the `New-Item` expects a string. The
493+
tilde character is treated as a literal character. To change to the newly
494+
created directory, you must qualify the path with the tilde character.
495+
496+
```powershell
497+
PS D:\temp> Set-Location ~
498+
PS C:\Users\user2> New-Item -Type Directory -Name ~
499+
500+
Directory: C:\Users\user2
501+
502+
Mode LastWriteTime Length Name
503+
---- ------------- ------ ----
504+
d---- 5/6/2024 2:08 PM ~
505+
506+
PS C:\Users\user2> Set-Location ~
507+
PS C:\Users\user2> Set-Location .\~
508+
PS C:\Users\user2\~> $PWD
509+
510+
Path
511+
----
512+
C:\Users\user2\~
513+
```
514+
515+
When you use the tilde character with native commands, PowerShell passes the
516+
tilde as a literal character. Using the tilde in a path causes errors for
517+
native commands on Windows that don't support the tilde character.
518+
519+
```powershell
520+
PS D:\temp> $PWD
521+
522+
Path
523+
----
524+
D:\temp
525+
526+
PS D:\temp> Get-Item ~\repocache.clixml
527+
528+
Directory: C:\Users\user2
529+
530+
Mode LastWriteTime Length Name
531+
---- ------------- ------ ----
532+
-a--- 4/29/2024 3:42 PM 88177 repocache.clixml
533+
534+
PS D:\temp> more.com ~\repocache.clixml
535+
Cannot access file D:\temp\~\repocache.clixml
536+
```
537+
470538
## See also
471539

472540
- [about_Command_Syntax][05]

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

Lines changed: 18 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
description: Describes the special character sequences that control how PowerShell interprets the next characters in the sequence.
33
Locale: en-US
4-
ms.date: 02/23/2024
4+
ms.date: 05/06/2024
55
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_special_characters?view=powershell-7.2&WT.mc_id=ps-gethelp
66
schema: 2.0.0
77
title: about Special Characters
@@ -52,6 +52,7 @@ Special parsing tokens:
5252
| -------- | ------------------------------------------------------ |
5353
| `--` | Treat the remaining values as arguments not parameters |
5454
| `--%` | Stop parsing anything that follows |
55+
| `~` | Tilde |
5556

5657
## Null (`0)
5758

@@ -101,7 +102,7 @@ virtual terminal sequences. You can check the boolean value of
101102
supported.
102103

103104
For more information about ANSI escape sequences, see the
104-
[ANSI escape code][04] article in Wikipedia.
105+
[ANSI escape code][05] article in Wikipedia.
105106

106107
The following example outputs text with a green foreground color.
107108

@@ -212,7 +213,7 @@ character with no extra spacing added.
212213
There is a vertical tab♂between the words.
213214
```
214215

215-
The [Windows Terminal][05] renders the vertical tab character as a carriage
216+
The [Windows Terminal][06] renders the vertical tab character as a carriage
216217
return and line feed. The rest of the output is printed at the beginning of the
217218
next line.
218219

@@ -291,13 +292,23 @@ C:\Users\username $HOME
291292

292293
For more information about the stop-parsing token, see [about_Parsing][02].
293294

295+
## Tilde (~)
296+
297+
The tilde character (`~`) has special meaning in PowerShell. When it's used
298+
with PowerShell commands at the beginning of a path, PowerShell expands the
299+
tilde character to the user's home directory. If you use the tilde character
300+
anywhere else in a path, it's treated as a literal character.
301+
302+
For more information about the stop-parsing token, see [about_Parsing][03].
303+
294304
## See also
295305

296-
- [about_Quoting_Rules][03]
306+
- [about_Quoting_Rules][04]
297307

298308
<!-- link references -->
299309
[01]: about_Parsing.md#line-continuation
300310
[02]: about_Parsing.md#the-stop-parsing-token
301-
[03]: about_Quoting_Rules.md
302-
[04]: https://wikipedia.org/wiki/ANSI_escape_code
303-
[05]: https://www.microsoft.com/p/windows-terminal/9n0dx20hk701
311+
[03]: about_Parsing.md#tilde-
312+
[04]: about_Quoting_Rules.md
313+
[05]: https://wikipedia.org/wiki/ANSI_escape_code
314+
[06]: https://www.microsoft.com/p/windows-terminal/9n0dx20hk701

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

Lines changed: 69 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
description: Describes how PowerShell parses commands.
33
Locale: en-US
4-
ms.date: 02/26/2024
4+
ms.date: 05/06/2024
55
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_parsing?view=powershell-7.3&WT.mc_id=ps-gethelp
66
schema: 2.0.0
77
title: about Parsing
@@ -465,6 +465,74 @@ Arg 2 is <-->
465465
Arg 3 is <-c>
466466
```
467467

468+
## Tilde (~)
469+
470+
The tilde character (`~`) has special meaning in PowerShell. When it's used
471+
with PowerShell commands at the beginning of a path, the tilde character is
472+
expanded to the user's home directory. If the tilde character is used anywhere
473+
else in a path, it's treated as a literal character.
474+
475+
```powershell
476+
PS D:\temp> $PWD
477+
478+
Path
479+
----
480+
D:\temp
481+
482+
PS D:\temp> Set-Location ~
483+
PS C:\Users\user2> $PWD
484+
485+
Path
486+
----
487+
C:\Users\user2
488+
```
489+
490+
In this example, the **Name** parameter of the `New-Item` expects a string. The
491+
tilde character is treated as a literal character. To change to the newly
492+
created directory, you must qualify the path with the tilde character.
493+
494+
```powershell
495+
PS D:\temp> Set-Location ~
496+
PS C:\Users\user2> New-Item -Type Directory -Name ~
497+
498+
Directory: C:\Users\user2
499+
500+
Mode LastWriteTime Length Name
501+
---- ------------- ------ ----
502+
d---- 5/6/2024 2:08 PM ~
503+
504+
PS C:\Users\user2> Set-Location ~
505+
PS C:\Users\user2> Set-Location .\~
506+
PS C:\Users\user2\~> $PWD
507+
508+
Path
509+
----
510+
C:\Users\user2\~
511+
```
512+
513+
When you use the tilde character with native commands, PowerShell passes the
514+
tilde as a literal character. Using the tilde in a path causes errors for
515+
native commands on Windows that don't support the tilde character.
516+
517+
```powershell
518+
PS D:\temp> $PWD
519+
520+
Path
521+
----
522+
D:\temp
523+
524+
PS D:\temp> Get-Item ~\repocache.clixml
525+
526+
Directory: C:\Users\user2
527+
528+
Mode LastWriteTime Length Name
529+
---- ------------- ------ ----
530+
-a--- 4/29/2024 3:42 PM 88177 repocache.clixml
531+
532+
PS D:\temp> more.com ~\repocache.clixml
533+
Cannot access file D:\temp\~\repocache.clixml
534+
```
535+
468536
## See also
469537

470538
- [about_Command_Syntax][04]

0 commit comments

Comments
 (0)