From 7acdb761d6e9c1a1820184c95f9ea156815bd0fd Mon Sep 17 00:00:00 2001
From: Jeremy McClure <jeremy@jeremymcclure.com>
Date: Wed, 29 Jul 2026 12:15:06 -0400
Subject: [PATCH] zsh: detect eza --hyperlink capability, fix 'cannot take a
 value' on Debian's older eza

Newer eza (clap) treats --hyperlink as taking an optional value, so the
oh-my-zsh plugin's bare --hyperlink eats the next path arg (la / ->
invalid value '/'). The previous fix glued --hyperlink=always to avoid
that. But Debian ships an older eza where --hyperlink is a pure boolean
that rejects a value, so --hyperlink=always errors with 'Flag
--hyperlink cannot take a value'.

Detect the installed eza's behavior via 'eza --help | grep <WHEN>':
- newer eza: use --hyperlink=always (glued, avoids path-eating)
- older eza: use bare --hyperlink (boolean, doesn't eat tokens so the
  original bug doesn't apply)
Apply the chosen form to every eza alias. Both paths keep hyperlinks on
and paths working.
---
 zsh/README.md |  7 ++++++-
 zsh/zshrc     | 19 ++++++++++++++-----
 2 files changed, 20 insertions(+), 6 deletions(-)

diff --git a/zsh/README.md b/zsh/README.md
index db693f2..f5a2548 100644
--- a/zsh/README.md
+++ b/zsh/README.md
@@ -90,7 +90,12 @@ Each is enabled only when the binary is present (`command -v`):
 
 ## Eza Hyperlinks — Implementation Note
 
-`zshrc` does **not** set the oh-my-zsh `eza` plugin's `hyperlink` zstyle. The plugin emits a bare `--hyperlink` flag, which eza (clap) treats as taking the *next token* as its optional value — so `la /` fails with `invalid value '/'`. Instead, after oh-my-zsh loads, the aliases are rewritten to append the glued `--hyperlink=always` form, which can't eat a following path argument. Hyperlinks stay on and paths keep working.
+`zshrc` does **not** set the oh-my-zsh `eza` plugin's `hyperlink` zstyle (the plugin's bare `--hyperlink` causes issues). Instead, after oh-my-zsh loads, the aliases are rewritten to append the correct hyperlink flag for the installed eza version:
+
+- **Newer eza** (help shows `--hyperlink [<WHEN>]`): the oh-my-zsh plugin's bare `--hyperlink` is treated by clap as taking the *next token* as its optional value, so `la /` fails with `invalid value '/'`. We append the glued `--hyperlink=always` form, which can't eat a following path argument.
+- **Older eza** (e.g. Debian's, where `--hyperlink` is a pure boolean): `--hyperlink=always` is rejected with `Flag --hyperlink cannot take a value`. We detect this via `eza --help` and fall back to the bare `--hyperlink`, which is safe here because boolean flags don't consume the next token (the path-eating bug doesn't apply).
+
+Detection runs once at shell start via `eza --help | grep '<WHEN>'`; the right form is applied to every eza alias. Hyperlinks stay on and paths keep working across eza versions.
 
 ## Auto-Update Behavior
 
diff --git a/zsh/zshrc b/zsh/zshrc
index 3ccb9d7..44cb754 100644
--- a/zsh/zshrc
+++ b/zsh/zshrc
@@ -132,13 +132,22 @@ zstyle ':completion:*' special-dirs true
 
 source $OHMYZSH/oh-my-zsh.sh
 
-# Re-enable eza hyperlinks safely. The oh-my-zsh eza plugin's bare
-# --hyperlink flag eats the following path argument (eza clap optional-value),
-# so we append the glued --hyperlink=always form to each eza alias instead.
+# Re-enable eza hyperlinks, picking the flag form the installed eza supports.
+# Newer eza: --hyperlink takes an optional value; the oh-my-zsh plugin's bare
+# --hyperlink would eat the following path arg (e.g. `la /` -> invalid value '/'),
+# so we use the glued --hyperlink=always form.
+# Older eza (e.g. Debian's): --hyperlink is a pure boolean and rejects a value,
+# so --hyperlink=always errors; the bare --hyperlink is correct and safe there
+# (boolean flags don't consume the next token, so the path-eating bug doesn't
+# apply).
+_hl_flag="--hyperlink"
+if command -v eza >/dev/null && eza --help 2>&1 | grep -q -- '--hyperlink.*<WHEN>'; then
+  _hl_flag="--hyperlink=always"
+fi
 for _ea in la ldot lD lDD ll ls lsd lsdl lS lT; do
-  (( $+aliases[$_ea] )) && alias "$_ea"="${aliases[$_ea]} --hyperlink=always"
+  (( $+aliases[$_ea] )) && alias "$_ea"="${aliases[$_ea]} $_hl_flag"
 done
-unset _ea
+unset _ea _hl_flag
 
 # --- Tool integrations (self-configuring: enabled only when the tool exists) ---