diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 0b894897d1..d6d0f1a9f8 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2729,16 +2729,16 @@ vim.keymap.set({mode}, {lhs}, {rhs}, {opts}) *vim.keymap.set()*
Lua module: vim.fs *vim.fs*
vim.fs.basename({file}) *vim.fs.basename()*
- Return the basename of the given file or directory
+ Return the basename of the given path
Parameters: ~
- • {file} (string) File or directory
+ • {file} (string) Path
Return: ~
(string|nil) Basename of {file}
vim.fs.dir({path}, {opts}) *vim.fs.dir()*
- Return an iterator over the files and directories located in {path}
+ Return an iterator over the items located in {path}
Parameters: ~
• {path} (string) An absolute or relative path to the directory to
@@ -2751,30 +2751,32 @@ vim.fs.dir({path}, {opts}) *vim.fs.dir()*
current directory. Only useful when depth > 1
Return: ~
- Iterator over files and directories in {path}. Each iteration yields
- two values: name and type. Each "name" is the basename of the file or
- directory relative to {path}. Type is one of "file" or "directory".
+ Iterator over items in {path}. Each iteration yields two values:
+ "name" and "type". "name" is the basename of the item relative to
+ {path}. "type" is one of the following: "file", "directory", "link",
+ "fifo", "socket", "char", "block", "unknown".
vim.fs.dirname({file}) *vim.fs.dirname()*
- Return the parent directory of the given file or directory
+ Return the parent directory of the given path
Parameters: ~
- • {file} (string) File or directory
+ • {file} (string) Path
Return: ~
(string|nil) Parent directory of {file}
vim.fs.find({names}, {opts}) *vim.fs.find()*
- Find files or directories in the given path.
+ Find files or directories (or other items as specified by `opts.type`) in
+ the given path.
- Finds any files or directories given in {names} starting from {path}. If
- {upward} is "true" then the search traverses upward through parent
- directories; otherwise, the search traverses downward. Note that downward
- searches are recursive and may search through many directories! If {stop}
- is non-nil, then the search stops when the directory given in {stop} is
- reached. The search terminates when {limit} (default 1) matches are found.
- The search can be narrowed to find only files or only directories by
- specifying {type} to be "file" or "directory", respectively.
+ Finds items given in {names} starting from {path}. If {upward} is "true"
+ then the search traverses upward through parent directories; otherwise,
+ the search traverses downward. Note that downward searches are recursive
+ and may search through many directories! If {stop} is non-nil, then the
+ search stops when the directory given in {stop} is reached. The search
+ terminates when {limit} (default 1) matches are found. You can set {type}
+ to "file", "directory", "link", "socket", "char", "block", or "fifo" to
+ narrow the search to find only that type.
Examples: >lua
@@ -2799,14 +2801,13 @@ vim.fs.find({names}, {opts}) *vim.fs.find()*
Parameters: ~
• {names} (string|table|fun(name: string, path: string): boolean) Names
- of the files and directories to find. Must be base names,
- paths and globs are not supported when {names} is a string or
- a table. If {names} is a function, it is called for each
- traversed file and directory with args:
+ of the items to find. Must be base names, paths and globs are
+ not supported when {names} is a string or a table. If {names}
+ is a function, it is called for each traversed item with
+ args:
• name: base name of the current item
• path: full path of the current item The function should
- return `true` if the given file or directory is considered
- a match.
+ return `true` if the given item is considered a match.
• {opts} (table) Optional keyword arguments:
• path (string): Path to begin searching from. If omitted,
the |current-directory| is used.
@@ -2815,16 +2816,14 @@ vim.fs.find({names}, {opts}) *vim.fs.find()*
directories (recursively).
• stop (string): Stop searching when this directory is
reached. The directory itself is not searched.
- • type (string): Find only files ("file") or directories
- ("directory"). If omitted, both files and directories that
- match {names} are included.
+ • type (string): Find only items of the given type. If
+ omitted, all items that match {names} are included.
• limit (number, default 1): Stop the search after finding
this many matches. Use `math.huge` to place no limit on the
number of matches.
Return: ~
- (table) Normalized paths |vim.fs.normalize()| of all matching files or
- directories
+ (table) Normalized paths |vim.fs.normalize()| of all matching items
vim.fs.joinpath({...}) *vim.fs.joinpath()*
Concatenate directories and/or file paths into a single path with
@@ -2864,7 +2863,7 @@ vim.fs.normalize({path}, {opts}) *vim.fs.normalize()*
(string) Normalized path
vim.fs.parents({start}) *vim.fs.parents()*
- Iterate over all the parents of the given file or directory.
+ Iterate over all the parents of the given path.
Example: >lua
@@ -2882,7 +2881,7 @@ vim.fs.parents({start}) *vim.fs.parents()*
<
Parameters: ~
- • {start} (string) Initial file or directory.
+ • {start} (string) Initial path.
Return: ~
(function) Iterator
diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
index 842767098c..92966523c0 100644
--- a/runtime/lua/vim/fs.lua
+++ b/runtime/lua/vim/fs.lua
@@ -2,7 +2,7 @@ local M = {}
local iswin = vim.uv.os_uname().sysname == 'Windows_NT'
---- Iterate over all the parents of the given file or directory.
+--- Iterate over all the parents of the given path.
---
--- Example:
--- lua
@@ -19,7 +19,7 @@ local iswin = vim.uv.os_uname().sysname == 'Windows_NT'
--- end
---
---
----@param start (string) Initial file or directory.
+---@param start (string) Initial path.
---@return function Iterator
function M.parents(start)
return function(_, dir)
@@ -34,9 +34,9 @@ function M.parents(start)
start
end
---- Return the parent directory of the given file or directory
+--- Return the parent directory of the given path
---
----@param file (string) File or directory
+---@param file (string) Path
---@return string|nil Parent directory of {file}
function M.dirname(file)
if file == nil then
@@ -57,9 +57,9 @@ function M.dirname(file)
return (dir:gsub('\\', '/'))
end
---- Return the basename of the given file or directory
+--- Return the basename of the given path
---
----@param file string File or directory
+---@param file string Path
---@return string|nil Basename of {file}
function M.basename(file)
if file == nil then
@@ -83,7 +83,7 @@ end
---@alias Iterator fun(): string?, string?
---- Return an iterator over the files and directories located in {path}
+--- Return an iterator over the items located in {path}
---
---@param path (string) An absolute or relative path to the directory to iterate
--- over. The path is first normalized |vim.fs.normalize()|.
@@ -93,9 +93,10 @@ end
--- to control traversal. Return false to stop searching the current directory.
--- Only useful when depth > 1
---
----@return Iterator over files and directories in {path}. Each iteration yields
---- two values: name and type. Each "name" is the basename of the file or
---- directory relative to {path}. Type is one of "file" or "directory".
+---@return Iterator over items in {path}. Each iteration yields two values: "name" and "type".
+--- "name" is the basename of the item relative to {path}.
+--- "type" is one of the following:
+--- "file", "directory", "link", "fifo", "socket", "char", "block", "unknown".
function M.dir(path, opts)
opts = opts or {}
@@ -142,16 +143,16 @@ function M.dir(path, opts)
end)
end
---- Find files or directories in the given path.
+--- Find files or directories (or other items as specified by `opts.type`) in the given path.
---
---- Finds any files or directories given in {names} starting from {path}. If
---- {upward} is "true" then the search traverses upward through parent
---- directories; otherwise, the search traverses downward. Note that downward
---- searches are recursive and may search through many directories! If {stop}
---- is non-nil, then the search stops when the directory given in {stop} is
---- reached. The search terminates when {limit} (default 1) matches are found.
---- The search can be narrowed to find only files or only directories by
---- specifying {type} to be "file" or "directory", respectively.
+--- Finds items given in {names} starting from {path}. If {upward} is "true"
+--- then the search traverses upward through parent directories; otherwise,
+--- the search traverses downward. Note that downward searches are recursive
+--- and may search through many directories! If {stop} is non-nil, then the
+--- search stops when the directory given in {stop} is reached. The search
+--- terminates when {limit} (default 1) matches are found. You can set {type}
+--- to "file", "directory", "link", "socket", "char", "block", or "fifo"
+--- to narrow the search to find only that type.
---
--- Examples:
--- lua
@@ -174,13 +175,12 @@ end
--- end, {limit = math.huge, type = 'file'})
---
---
----@param names (string|table|fun(name: string, path: string): boolean) Names of the files
---- and directories to find.
+---@param names (string|table|fun(name: string, path: string): boolean) Names of the items to find.
--- Must be base names, paths and globs are not supported when {names} is a string or a table.
---- If {names} is a function, it is called for each traversed file and directory with args:
+--- If {names} is a function, it is called for each traversed item with args:
--- - name: base name of the current item
--- - path: full path of the current item
---- The function should return `true` if the given file or directory is considered a match.
+--- The function should return `true` if the given item is considered a match.
---
---@param opts (table) Optional keyword arguments:
--- - path (string): Path to begin searching from. If
@@ -191,14 +191,12 @@ end
--- (recursively).
--- - stop (string): Stop searching when this directory is
--- reached. The directory itself is not searched.
---- - type (string): Find only files ("file") or
---- directories ("directory"). If omitted, both
---- files and directories that match {names} are
---- included.
+--- - type (string): Find only items of the given type.
+--- If omitted, all items that match {names} are included.
--- - limit (number, default 1): Stop the search after
--- finding this many matches. Use `math.huge` to
--- place no limit on the number of matches.
----@return (table) Normalized paths |vim.fs.normalize()| of all matching files or directories
+---@return (table) Normalized paths |vim.fs.normalize()| of all matching items
function M.find(names, opts)
opts = opts or {}
vim.validate({