From 6cdab150bc161a35ca6356a4d1b4add17c52eb4b Mon Sep 17 00:00:00 2001 From: "Justin M. Keyes" Date: Thu, 30 Jul 2026 15:09:19 -0400 Subject: [PATCH] docs: misc #41063 --- runtime/doc/autocmd.txt | 9 ++++++--- runtime/doc/lua.txt | 39 ++++++++++++++++++--------------------- runtime/doc/news.txt | 1 + runtime/doc/windows.txt | 19 ++++++++++++------- runtime/lua/vim/fs.lua | 35 +++++++++++++++++------------------ 5 files changed, 54 insertions(+), 49 deletions(-) diff --git a/runtime/doc/autocmd.txt b/runtime/doc/autocmd.txt index b316cef456..f73661ec4e 100644 --- a/runtime/doc/autocmd.txt +++ b/runtime/doc/autocmd.txt @@ -1401,10 +1401,13 @@ VimLeavePre Before exiting Vim, just before writing the Not triggered if |v:dying| is 2 or more. *VimResized* -VimResized After the Vim window was resized, thus 'lines' - and/or 'columns' changed. Not when starting - up though. +VimResized After Nvim itself was resized: 'lines' and/or + 'columns' changed. But not during |startup|. + To ensure the window layout is always + "equalized" on resize: > + :autocmd VimResized * wincmd = +< *VimResume* VimResume After Nvim resumes from |suspend| state. diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 851d25cb8a..73cf5859f4 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -2647,10 +2647,8 @@ vim.fs.dir({path}, {opts}) *vim.fs.dir()* skipping. • {follow}? (`boolean`, default: `false`) Follow symbolic links. - • {normalize}? (`boolean`, default: `true`) Normalize {path} - via |vim.fs.normalize()|. Set `false` to use {path} - literally, e.g. to list a directory whose name contains `~` - or `$`. + • {normalize}? (`boolean`, default: `true`) Expand "~" and "$" + in {path} before scanning the directory. • {skip}? (`fun(dir_name: string): boolean`) Predicate to control traversal. Return false to stop searching the current directory. Only useful when depth > 1 Return an @@ -2797,11 +2795,10 @@ vim.fs.mkdir({path}, {opts}) *vim.fs.mkdir()* directories as necessary. vim.fs.normalize({path}, {opts}) *vim.fs.normalize()* - Normalize a path to a standard format. A tilde (~) character at the - beginning of the path is expanded to the user's home directory and - environment variables are also expanded. "." and ".." components are also - resolved, except when the path is relative and trying to resolve it would - result in an absolute path. + Normalize a path to a standard format. Expands environment variables, and + tilde "~" at the beginning of the path. Resolves "." and ".." components, + except when the path is relative and resolving it would produce an + absolute path. • "." as the only part in a relative path: • "." => "." • "././" => "." @@ -2811,19 +2808,19 @@ vim.fs.normalize({path}, {opts}) *vim.fs.normalize()* • ".." in the root directory returns the root directory. • "/../../" => "/" - On Windows, backslash (\) characters are converted to forward slashes (/). + On Windows, backslashes (`\`) are converted to forward slashes (`/`). - Examples: > - [[C:\Users\jdoe]] => "C:/Users/jdoe" - "~/src/neovim" => "/home/jdoe/src/neovim" - "$XDG_CONFIG_HOME/nvim/init.vim" => "/Users/jdoe/.config/nvim/init.vim" - "~/src/nvim/api/../tui/./tui.c" => "/home/jdoe/src/nvim/tui/tui.c" - "./foo/bar" => "foo/bar" - "foo/../../../bar" => "../../bar" - "/home/jdoe/../../../bar" => "/bar" - "C:foo/../../baz" => "C:../baz" - "C:/foo/../../baz" => "C:/baz" - [[\\?\UNC\server\share\foo\..\..\..\bar]] => "//?/UNC/server/share/bar" + Examples: >lua + [[C:\Users\jdoe]] --> "C:/Users/jdoe" + "~/src/neovim" --> "/home/jdoe/src/neovim" + "$XDG_CONFIG_HOME/nvim/init.vim" --> "/Users/jdoe/.config/nvim/init.vim" + "~/src/nvim/api/../tui/./tui.c" --> "/home/jdoe/src/nvim/tui/tui.c" + "./foo/bar" --> "foo/bar" + "foo/../../../bar" --> "../../bar" + "/home/jdoe/../../../bar" --> "/bar" + "C:foo/../../baz" --> "C:../baz" + "C:/foo/../../baz" --> "C:/baz" + [[\\?\UNC\server\share\foo\..\..\..\bar]] --> "//?/UNC/server/share/bar" < Attributes: ~ diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index a3de344e1a..de1ab37d42 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -315,6 +315,7 @@ LUA write binary data. • |vim.fs.dir()| with `opts.err=true`, reports errors. An inaccessible root dir yields a single (name, nil, err) item. +• |vim.fs.dir()| gained a `normalize` parameter. • |vim.fs.find()| returns a list of errors as its second return value. • |vim.fs.mkdir()| creates directories, including parent directories with `opts.parents=true`. diff --git a/runtime/doc/windows.txt b/runtime/doc/windows.txt index 727427f5a5..1a486bb515 100644 --- a/runtime/doc/windows.txt +++ b/runtime/doc/windows.txt @@ -562,13 +562,18 @@ CTRL-W T Move the current window to a new tabpage. This fails if *CTRL-W_=* CTRL-W = Make all windows (almost) equally high and wide, but use - 'winheight' and 'winwidth' for the current window. - Windows with 'winfixheight' set keep their height and windows - with 'winfixwidth' set keep their width. - To equalize only vertically (make window equally high) use - `vertical wincmd =` . - To equalize only horizontally (make window equally wide) use - `horizontal wincmd =` . + 'winheight' and 'winwidth' for the current window. Windows + with 'winfixheight' set keep their height, and windows with + 'winfixwidth' set keep their width. + + To equalize only vertically (each window equally high) use: > + :vertical wincmd = +< + To equalize only horizontally (each window equally wide) use: > + :horizontal wincmd = +< + To equalize windows when Nvim itself is resized, see + |VimResized|. :res[ize] -N *:res* *:resize* *CTRL-W_-* CTRL-W - Decrease current window height by N (default 1). diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua index 57e0da4650..1c48944807 100644 --- a/runtime/lua/vim/fs.lua +++ b/runtime/lua/vim/fs.lua @@ -191,8 +191,7 @@ end --- (default: `false`) --- @field follow? boolean --- ---- Normalize {path} via |vim.fs.normalize()|. Set `false` to use {path} literally, e.g. to list a ---- directory whose name contains `~` or `$`. +--- Expand "~" and "$" in {path} before scanning the directory. --- (default: `true`) --- @field normalize? boolean @@ -678,10 +677,10 @@ end --- (default: `true` in Windows, `false` otherwise) --- @field win? boolean ---- Normalize a path to a standard format. A tilde (~) character at the beginning of the path is ---- expanded to the user's home directory and environment variables are also expanded. "." and ".." ---- components are also resolved, except when the path is relative and trying to resolve it would ---- result in an absolute path. +--- Normalize a path to a standard format. Expands environment variables, and tilde "~" at the +--- beginning of the path. Resolves "." and ".." components, except when the path is relative and +--- resolving it would produce an absolute path. +--- --- - "." as the only part in a relative path: --- - "." => "." --- - "././" => "." @@ -691,20 +690,20 @@ end --- - ".." in the root directory returns the root directory. --- - "/../../" => "/" --- ---- On Windows, backslash (\) characters are converted to forward slashes (/). +--- On Windows, backslashes (`\`) are converted to forward slashes (`/`). --- --- Examples: ---- ``` ---- [[C:\Users\jdoe]] => "C:/Users/jdoe" ---- "~/src/neovim" => "/home/jdoe/src/neovim" ---- "$XDG_CONFIG_HOME/nvim/init.vim" => "/Users/jdoe/.config/nvim/init.vim" ---- "~/src/nvim/api/../tui/./tui.c" => "/home/jdoe/src/nvim/tui/tui.c" ---- "./foo/bar" => "foo/bar" ---- "foo/../../../bar" => "../../bar" ---- "/home/jdoe/../../../bar" => "/bar" ---- "C:foo/../../baz" => "C:../baz" ---- "C:/foo/../../baz" => "C:/baz" ---- [[\\?\UNC\server\share\foo\..\..\..\bar]] => "//?/UNC/server/share/bar" +--- ```lua +--- [[C:\Users\jdoe]] --> "C:/Users/jdoe" +--- "~/src/neovim" --> "/home/jdoe/src/neovim" +--- "$XDG_CONFIG_HOME/nvim/init.vim" --> "/Users/jdoe/.config/nvim/init.vim" +--- "~/src/nvim/api/../tui/./tui.c" --> "/home/jdoe/src/nvim/tui/tui.c" +--- "./foo/bar" --> "foo/bar" +--- "foo/../../../bar" --> "../../bar" +--- "/home/jdoe/../../../bar" --> "/bar" +--- "C:foo/../../baz" --> "C:../baz" +--- "C:/foo/../../baz" --> "C:/baz" +--- [[\\?\UNC\server\share\foo\..\..\..\bar]] --> "//?/UNC/server/share/bar" --- ``` --- ---@since 10