feat(vim.fs): root() can specify "equal priority" #34276

2 files changed, 21 insertions, 4 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 55ad4f3cfc..b1816dc729 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -3216,6 +3216,10 @@ vim.fs.root({source}, {marker})                                *vim.fs.root()*
         vim.fs.root(0, function(name, path)
           return name:match('%.csproj$') ~= nil
         end)
+
+        -- Find the first ancestor directory containing EITHER "stylua.toml" or ".luarc.json"; if
+        -- not found, find the first ancestor containing ".git":
+        vim.fs.root(0, { { 'stylua.toml', '.luarc.json' }, '.git' })
 <
 
     Attributes: ~
@@ -3225,10 +3229,22 @@ vim.fs.root({source}, {marker})                                *vim.fs.root()*
       • {source}  (`integer|string`) Buffer number (0 for current buffer) or
                   file path (absolute or relative to the |current-directory|)
                   to begin the search from.
-      • {marker}  (`string|string[]|fun(name: string, path: string): boolean`)
-                  A marker, or list of markers, to search for. If a function,
-                  the function is called for each evaluated item and should
-                  return true if {name} and {path} are a match.
+      • {marker}  (`(string|string[]|fun(name: string, path: string): boolean)[]|string|fun(name: string, path: string): boolean`)
+                  A marker or a list of markers. A marker has one of three
+                  types: string, a list of strings or a function. The
+                  parameter also accepts a list of markers, each of which is
+                  any of those three types. If a marker is a function, it is
+                  called for each evaluated item and should return true if
+                  {name} and {path} are a match. If a list of markers is
+                  passed, each marker in the list is evaluated in order and
+                  the first marker which is matched returns the parent
+                  directory that it found. This allows listing markers with
+                  priority. E.g. - in the following list, a parent directory
+                  containing either 'a' or 'b' is searched for. If neither is
+                  found, then 'c' is searched for. So, 'c' has lower priority
+                  than 'a' and 'b' which have equal priority. >lua
+                          marker = { { 'a', 'b' }, 'c' }
+<
 
     Return: ~
         (`string?`) Directory path containing one of the given markers, or nil
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index a6ff5bd46b..4b3f29e3ed 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -171,6 +171,7 @@ LUA
 • Lua type annotations for `vim.uv`.
 • |vim.hl.range()| now allows multiple timed highlights.
 • |vim.tbl_extend()| and |vim.tbl_deep_extend()| now accept a function behavior argument.
+• |vim.fs.root()| can define "equal priority" via nested lists.
 
 OPTIONS