commit 715015d3b231a5d640f9bb109caf4d817c7f2bd6
parent db210dd2a41fe6a8745e00a6f2341881d696437d
Author: zeertzjq <zeertzjq@outlook.com>
Date: Sun, 4 Jan 2026 07:46:15 +0800
vim-patch:93eb081: runtime(doc): Clarify visual mark behavior in getpos(), setpos() (#37223)
Add documentation notes explaining that visual marks '< and '> have
different behaviors in getpos() and setpos().
Also fix a small typo.
closes: vim/vim#19070
https://github.com/vim/vim/commit/93eb081eee92180a495d72a495542b24a873e2f3
Co-authored-by: Larson, Eric <numeric.larson@gmail.com>
Diffstat:
3 files changed, 39 insertions(+), 9 deletions(-)
diff --git a/runtime/doc/vimfn.txt b/runtime/doc/vimfn.txt
@@ -3930,6 +3930,11 @@ getpos({expr}) *getpos()*
within the line. To get the character position in the line,
use |getcharpos()|.
+ The visual marks |'<| and |'>| refer to the beginning and end
+ of the visual selection relative to the buffer. Note that
+ this differs from |setpos()|, where they are relative to the
+ cursor position.
+
Note that for '< and '> Visual mode matters: when it is "V"
(visual line mode) the column of '< is zero and the column of
'> is a large number equal to |v:maxcol|.
@@ -9149,9 +9154,14 @@ setpos({expr}, {list}) *setpos()*
preferred column is not set. When it is present and setting a
mark position it is not used.
- Note that for '< and '> changing the line number may result in
- the marks to be effectively be swapped, so that '< is always
- before '>.
+ Note that for |'<| and |'>| changing the line number may
+ result in the marks to be effectively swapped, so that |'<| is
+ always before |'>|.
+
+ The visual marks |'<| and |'>| refer to the beginning and end
+ of the visual selection relative to the cursor position.
+ Note that this differs from |getpos()|, where they are
+ relative to the buffer.
Returns 0 when the position could be set, -1 otherwise.
An error message is given if {expr} is invalid.
diff --git a/runtime/lua/vim/_meta/vimfn.lua b/runtime/lua/vim/_meta/vimfn.lua
@@ -3532,6 +3532,11 @@ function vim.fn.getpid() end
--- within the line. To get the character position in the line,
--- use |getcharpos()|.
---
+--- The visual marks |'<| and |'>| refer to the beginning and end
+--- of the visual selection relative to the buffer. Note that
+--- this differs from |setpos()|, where they are relative to the
+--- cursor position.
+---
--- Note that for '< and '> Visual mode matters: when it is "V"
--- (visual line mode) the column of '< is zero and the column of
--- '> is a large number equal to |v:maxcol|.
@@ -8333,9 +8338,14 @@ function vim.fn.setmatches(list, win) end
--- preferred column is not set. When it is present and setting a
--- mark position it is not used.
---
---- Note that for '< and '> changing the line number may result in
---- the marks to be effectively be swapped, so that '< is always
---- before '>.
+--- Note that for |'<| and |'>| changing the line number may
+--- result in the marks to be effectively swapped, so that |'<| is
+--- always before |'>|.
+---
+--- The visual marks |'<| and |'>| refer to the beginning and end
+--- of the visual selection relative to the cursor position.
+--- Note that this differs from |getpos()|, where they are
+--- relative to the buffer.
---
--- Returns 0 when the position could be set, -1 otherwise.
--- An error message is given if {expr} is invalid.
diff --git a/src/nvim/eval.lua b/src/nvim/eval.lua
@@ -4406,6 +4406,11 @@ M.funcs = {
within the line. To get the character position in the line,
use |getcharpos()|.
+ The visual marks |'<| and |'>| refer to the beginning and end
+ of the visual selection relative to the buffer. Note that
+ this differs from |setpos()|, where they are relative to the
+ cursor position.
+
Note that for '< and '> Visual mode matters: when it is "V"
(visual line mode) the column of '< is zero and the column of
'> is a large number equal to |v:maxcol|.
@@ -10108,9 +10113,14 @@ M.funcs = {
preferred column is not set. When it is present and setting a
mark position it is not used.
- Note that for '< and '> changing the line number may result in
- the marks to be effectively be swapped, so that '< is always
- before '>.
+ Note that for |'<| and |'>| changing the line number may
+ result in the marks to be effectively swapped, so that |'<| is
+ always before |'>|.
+
+ The visual marks |'<| and |'>| refer to the beginning and end
+ of the visual selection relative to the cursor position.
+ Note that this differs from |getpos()|, where they are
+ relative to the buffer.
Returns 0 when the position could be set, -1 otherwise.
An error message is given if {expr} is invalid.
