From: Hirohito Higashi <h.east.727@gmail.com>
Date: Sat, 25 Jul 2026 16:40:40 +0000 (+0000)
Subject: runtime(doc): clarify expandcmd() and "~" behaviour
X-Git-Tag: v9.2.0855~2
X-Git-Url: http://git.ipfire.org/gitweb/index.cgi?a=commitdiff_plain;h=770eb7db17c44e41fc4eb1975d67f9ec022edb58;p=thirdparty%2Fvim.git

runtime(doc): clarify expandcmd() and "~" behaviour

fixes: #20793

Signed-off-by: Hirohito Higashi <h.east.727@gmail.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>
---

diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt
index dc668c3a91..1f14e75281 100644
--- a/runtime/doc/builtin.txt
+++ b/runtime/doc/builtin.txt
@@ -3099,6 +3099,10 @@ expandcmd({string} [, {options}])			*expandcmd()*
 		like with |expand()|, and environment variables, anywhere in
 		{string}.  "~user" and "~/path" are only expanded at the
 		start.
+		The expansion is done in two steps: the special keywords are
+		evaluated first, then "~" and environment variables are
+		expanded in the result.  Thus `expand('%:~')` keeps the "~",
+		while `expandcmd('%:~')` returns the full path.
 
 		The following items are supported in the {options} Dict
 		argument: