pwsh: handling `z ~` and `z` separately

This patch enables the capability of navigating to the current user's home
directory with `z` when cwd is on a PSDrive that does not have a definition
of the `HOME` location.

Context: The fact that `~` can be counterintuitive on PowerShell, as it's
relative to the cwd, **and its value is defined with a `.Home` property of
cwd's PSProvider\[1]. Not all PSProviders however define this property, leaving
that sometimes you cannot navigate to the undefined `HOME` location with `~`.

To validate this, you can use `Get-PSDrive` to iterate your PSDrives and see
which providers define a `Home` property. On Windows,

```plain
Get-PSDrive C,HKLM | select Name,{$_.Provider.Name},{$_.Provider.Home}

Name $_.Provider.Name $_.Provider.Home
---- ---------------- ----------------
C    FileSystem       C:\Users\<username>
HKLM Registry
```

or on Linux/macOS,

```plain
Get-PSDrive /,Function | select Name,{$_.Provider.Name},{$_.Provider.Home}

Name     $_.Provider.Name $_.Provider.Home
----     ---------------- ----------------
/        FileSystem       /Users/<username>
Function Function
```

When cwd is on a PSDrive without a defined `HOME` location, the original
`Set-Location` alias `cd` in PowerShell handles this case by falling back
to the user's home directory when no argument is provided\[2], and when `~`
is explicitly provided, it results in an error.

```plain
PS C:\> Set-Location Function:
PS Function:\> cd ~
Home location for this provider is not set. To set the home location, call "(get-psprovider 'Function').Home = 'path'".
PS Function:\> cd
PS C:\Users\<username>\>
```

This patch implements the same behavior for `z` by handling `z ~` and `z` separately.

\[1]: https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_providers
\[2]: https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.management/set-location?#-path

Signed-off-by: Chawye Hsu <su+git@chawyehsu.com>
This commit is contained in:
Chawye Hsu 2026-01-13 17:44:53 +08:00
parent d7458b756e
commit 976a721020
No known key found for this signature in database
GPG Key ID: 5AE5178B3E1624DA
1 changed files with 8 additions and 1 deletions

View File

@ -28,7 +28,11 @@ function global:__zoxide_pwd {
# cd + custom logic based on the value of _ZO_ECHO.
function global:__zoxide_cd($dir, $literal) {
$dir = if ($literal) {
Set-Location -LiteralPath $dir -Passthru -ErrorAction Stop
if ($null -eq $dir) {
Set-Location
} else {
Set-Location -LiteralPath $dir -Passthru -ErrorAction Stop
}
} else {
if ($dir -eq '-' -and ($PSVersionTable.PSVersion -lt 6.1)) {
Write-Error "cd - is not supported below PowerShell 6.1. Please upgrade your version of PowerShell."
@ -101,6 +105,9 @@ if ($global:__zoxide_hooked -ne 1) {
# Jump to a directory using only keywords.
function global:__zoxide_z {
if ($args.Length -eq 0) {
__zoxide_cd $null $true
}
elseif ($args.Length -eq 1 -and $args[0] -eq '~') {
__zoxide_cd ~ $true
}
elseif ($args.Length -eq 1 -and ($args[0] -eq '-' -or $args[0] -eq '+')) {