From f636479b70df5b96f4095cae2c86f0a61ab4a6f2 Mon Sep 17 00:00:00 2001
From: Julian Prein <julian@druck.dev>
Date: Fri, 20 Jun 2025 12:24:17 +0200
Subject: [PATCH] zsh:diffcmds: Improve usage description

---
 .config/zsh/zshrc.d/40-functions.zsh | 22 +++++++++++++++-------
 1 file changed, 15 insertions(+), 7 deletions(-)

diff --git a/.config/zsh/zshrc.d/40-functions.zsh b/.config/zsh/zshrc.d/40-functions.zsh
index 223230a..df25595 100644
--- a/.config/zsh/zshrc.d/40-functions.zsh
+++ b/.config/zsh/zshrc.d/40-functions.zsh
@@ -651,16 +651,24 @@ psofof() {
 	lsof "$@" | tail -n +2 | awk '{ print $2 }' | sort -u
 }
 
-# diff the output of multiple commands following the same pattern.
-# Uses vimdiff if it is installed and EDITOR or VISUAL are matching `vi`.
-# Pipelines can be executed by quoting the pipes.
+# diff the output of multiple commands following the same pattern. For each
+# argument behind `--`, the template-command will be executed after replacing
+# the placeholder `%%` with the argument. If no placeholder is given, the
+# argument will be placed at the end. Pipelines can be executed by
+# quoting/escaping the pipes.
+#
+# Uses vimdiff if it is installed and EDITOR or VISUAL are matching `vi` or if
+# more than 2 arguments were passed.
 #
 # Example:
-# diffcmds cat -n %% '|' head -- file1 file2
-#
-# would be equivalent to:
-# vimdiff =(cat -n file1 | head) =(cat -n file2 | head)
+#     diffcmds cat -n %% '|' head -5 -- file1 file2
+# would run:
+#     vimdiff =(cat -n file1 | head -5) =(cat -n file2 | head -5)
 #
+# or simply:
+#     diffcmds xxd -- file1 file2
+# for:
+#     vimdiff =(xxd file1) =(xxd file2)
 diffcmds() {
 	# TODO: Support own arguments for example to switch the placeholder or the
 	#       diffcmd