From 976a721020d665c942134455fc816dba2400d184 Mon Sep 17 00:00:00 2001
From: Chawye Hsu <su+git@chawyehsu.com>
Date: Tue, 13 Jan 2026 17:44:53 +0800
Subject: [PATCH] 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>
---
 templates/powershell.txt | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/templates/powershell.txt b/templates/powershell.txt
index 046061c..4312dbb 100644
--- a/templates/powershell.txt
+++ b/templates/powershell.txt
@@ -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 '+')) {