[vim/vim] Docs don't match behaviour for global-local options and `:setlocal {option}<` (Issue #14062)

17 views
Skip to first unread message

Matt Ellis

unread,
Feb 20, 2024, 9:32:56 AMFeb 20
to vim/vim, Subscribed

Steps to reproduce

setglobal scrolloff=10
setlocal scrolloff=20
setlocal scrolloff<
setlocal scrolloff?

Expected behaviour

According to the docs (:help :setlocal):

:setl[ocal] {option}<	Set the local value of {option} to its global value by
			copying the value.

:se[t] {option}<	For |global-local| options: Remove the local value of
			{option}, so that the global value will be used.

But these descriptions seem to be reversed. With a global-local option such as 'scrolloff', :setlocal scrolloff< will not copy the global value, but will remove the local value, because :setlocal scrolloff? shows the value is -1.

Conversely, :set scrolloff< sets the local value to the current global value.

Version of Vim

VIM - Vi IMproved 9.1 (2024 Jan 02, compiled Jan 4 2024 03:08:50)

Environment

MacOS 14.2.1
iTerm2 3.4.23

Logs and stack traces

No response


Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/issues/14062@github.com>

Matt Ellis

unread,
Feb 20, 2024, 9:47:22 AMFeb 20
to vim/vim, Subscribed

Actually, this only seems to be true for number-based options, including toggle options:

:set autoread
:setlocal autoread
:setlocal autoread<
:setlocal autoread?

This results in --autoread.

:setglobal scrolloff=10
:setlocal scrolloff=20
:setlocal scrolloff<
:setlocal scrolloff?

This results in scrolloff=-1.

But:

:setglobal backupcopy=yes
:setlocal backupcopy=no
:setlocal backupcopy<
:setlocal backupcopy?

This results in backupcopy=yes, rather than clearing the unset value.


Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/issues/14062/1954370716@github.com>

Christian Brabandt

unread,
Feb 20, 2024, 10:38:33 AMFeb 20
to vim/vim, Subscribed

:set autoread
:setlocal autoread
:setlocal autoread<
:setlocal autoread?

This results in --autoread.

:setglobal scrolloff=10
:setlocal scrolloff=20
:setlocal scrolloff<
:setlocal scrolloff?

This results in scrolloff=-1.

That is also correct. Since you cannot set the scrolloff option to a negative value this means Vim will use the global option value.

:setglobal backupcopy=yes
:setlocal backupcopy=no
:setlocal backupcopy<
:setlocal backupcopy?

This results in backupcopy=yes, rather than clearing the unset value.

I think Vim here copied the global option value to the local option value.

So what documentation fixes would you suggest?


Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/issues/14062/1954485139@github.com>

Matt Ellis

unread,
Feb 22, 2024, 6:26:56 AMFeb 22
to vim/vim, Subscribed

This is the original documentation:

:setl[ocal] {option}<	Set the local value of {option} to its global value by
			copying the value.

:se[t] {option}<	For |global-local| options: Remove the local value of
			{option}, so that the global value will be used.

To match the current behaviour, I would suggest something like:

:se[t] {option}<        Set the local value of {option} to its global value.
:setl[ocal] {option}<   For local options, this will copy the global value to
                        the local value. For global-local string options, this
                        will also copy the global value to the local value.
                        However, for number options and toggle options, this
                        will remove the local value of {option}, so that the
                        global value will be used.

This explains the current behaviour, but doesn't give any indication about why. There's an inconsistency in behaviour between string and number based options - one removes the local value, the other copies it. It makes sense that number based options remove the local option, because otherwise there's no way to remove the local value of a toggle option (and this could be added to the docs as context). But why does the same syntax do something different for string based options?


Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/issues/14062/1959252412@github.com>

Matt Ellis

unread,
Feb 22, 2024, 7:31:49 AMFeb 22
to vim/vim, Subscribed

Sigh. Nope, still got the current behaviour wrong. Here we go:

  • set {option}<
    • Local option (e.g. 'scroll' or 'signcolumn'): global value is copied to the local value
    • String global-local option (e.g. 'backupcopy'): local value is removed (set to empty string)
    • Number-based global-local option (e.g. 'scrolloff'):
      • If the local value is unset (-1), the local value remains at -1 (the effective value of the option is still global)
      • If the local value is set, then the global value is copied to the local value
  • setlocal {option}<
    • Local option (e.g. 'scroll' or 'signcolumn'): global value is copied to the local value
    • String global-local option (e.g. 'backupcopy'): global value is copied to the local value
    • Number-based global-local option (e.g. 'scrolloff'): the local value is removed (-1)

I don't know how to describe this succinctly. We can't say that it sets the local value of the option to its global value, because sometimes it copies and sometimes it removes the local value, and there's no consistency.

:set[t] {option}<	Set the effective value of {option} to its global
                        value.
			For string |global-local| options, the local value is
			removed, so that the global value will be used.
			For all other options, the global value is copied to
			the local value.
			
:setl[ocal] {option}<	Set the effective value of {option} to its global
                        value.
			For number and toggle |global-local| options, the
			local value is removed, so that the global value will
			be used.
			For all other options, including string |global-local|
			options, the global value is copied to the local
			value.

Note that the behaviour for |global-local| options is different for string or
number-based options.

In other words, I think this is a bug in the code, more than a problem of documentation.


Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/issues/14062/1959361856@github.com>

Christian Brabandt

unread,
Feb 24, 2024, 10:58:39 AMFeb 24
to vim/vim, Subscribed

I have seen quite a few discussions on the option handling description but not so much about the actual code. So let's for now just document this.


Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/issues/14062/1962408536@github.com>

Christian Brabandt

unread,
Feb 24, 2024, 11:05:14 AMFeb 24
to vim/vim, Subscribed

Closed #14062 as completed via 374e26a.


Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/issue/14062/issue_event/11911080111@github.com>

S. B. Tam

unread,
Feb 25, 2024, 1:35:43 AMFeb 25
to vim/vim, Subscribed

FWIW autoread and scrolloff are handled specially in the code.
https://github.com/vim/vim/blob/374e26aba2e5e0a220b1a7ce1934b0eb5f493e6c/src/option.c#L2085-L2092
https://github.com/vim/vim/blob/374e26aba2e5e0a220b1a7ce1934b0eb5f493e6c/src/option.c#L2146-L2158


Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.Message ID: <vim/vim/issues/14062/1962831539@github.com>

Reply all
Reply to author
Forward
0 new messages