From 67cbaf58c41a3db19c5014587e72d06be9e3d58e Mon Sep 17 00:00:00 2001
From: Gregory Anders <greg@gpanders.com>
Date: Sun, 15 May 2022 14:38:19 -0600
Subject: [PATCH 1/6] feat(fs): add vim.fs.parents()

vim.fs.parents() is a Lua iterator that returns the next parent
directory of the given file or directory on each iteration.
---
 runtime/doc/lua.txt             | 28 ++++++++++++++++++++++++++
 runtime/lua/vim/_editor.lua     |  1 +
 runtime/lua/vim/fs.lua          | 35 +++++++++++++++++++++++++++++++++
 scripts/gen_vimdoc.py           |  3 +++
 test/functional/lua/fs_spec.lua | 33 +++++++++++++++++++++++++++++++
 5 files changed, 100 insertions(+)
 create mode 100644 runtime/lua/vim/fs.lua
 create mode 100644 test/functional/lua/fs_spec.lua

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index dd1843ade3935b..8f74dca4185c48 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2147,4 +2147,32 @@ set({mode}, {lhs}, {rhs}, {opts})                           *vim.keymap.set()*
                 See also: ~
                     |nvim_set_keymap()|
 
+
+==============================================================================
+Lua module: fs                                                        *lua-fs*
+
+parents({start})                                            *vim.fs.parents()*
+                Iterate over all the parents of the given file or directory.
+
+                Example: >
+
+                 local root_dir
+                 for dir in vim.fs.parents(vim.api.nvim_buf_get_name(0)) do
+                   if vim.fn.isdirectory(dir .. "/.git") == 1 then
+                     root_dir = dir
+                     break
+                   end
+                 end
+
+                 if root_dir then
+                   print("Found git repository at", root_dir)
+                 end
+<
+
+                Parameters: ~
+                    {start}  (string) Initial file or directory.
+
+                Return: ~
+                    (function) Iterator
+
  vim:tw=78:ts=8:ft=help:norl:
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index c8a0aa82608bab..453aa6ac819145 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -50,6 +50,7 @@ for k, v in pairs({
   keymap = true,
   ui = true,
   health = true,
+  fs = true,
 }) do
   vim._submodules[k] = v
 end
diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
new file mode 100644
index 00000000000000..08d2e495d2cc28
--- /dev/null
+++ b/runtime/lua/vim/fs.lua
@@ -0,0 +1,35 @@
+local M = {}
+
+--- Iterate over all the parents of the given file or directory.
+---
+--- Example:
+--- <pre>
+--- local root_dir
+--- for dir in vim.fs.parents(vim.api.nvim_buf_get_name(0)) do
+---   if vim.fn.isdirectory(dir .. "/.git") == 1 then
+---     root_dir = dir
+---     break
+---   end
+--- end
+---
+--- if root_dir then
+---   print("Found git repository at", root_dir)
+--- end
+--- </pre>
+---
+---@param start (string) Initial file or directory.
+---@return (function) Iterator
+function M.parents(start)
+  return function(_, dir)
+    local parent = vim.fn.fnamemodify(dir, ":h")
+    if parent == dir then
+      return nil
+    end
+
+    return parent
+  end,
+    nil,
+    start
+end
+
+return M
diff --git a/scripts/gen_vimdoc.py b/scripts/gen_vimdoc.py
index 755749cef6bc56..790c2ba52deb93 100755
--- a/scripts/gen_vimdoc.py
+++ b/scripts/gen_vimdoc.py
@@ -134,6 +134,7 @@
             'ui.lua',
             'filetype.lua',
             'keymap.lua',
+            'fs.lua',
         ],
         'files': [
             'runtime/lua/vim/_editor.lua',
@@ -142,6 +143,7 @@
             'runtime/lua/vim/ui.lua',
             'runtime/lua/vim/filetype.lua',
             'runtime/lua/vim/keymap.lua',
+            'runtime/lua/vim/fs.lua',
         ],
         'file_patterns': '*.lua',
         'fn_name_prefix': '',
@@ -167,6 +169,7 @@
             'ui': 'vim.ui',
             'filetype': 'vim.filetype',
             'keymap': 'vim.keymap',
+            'fs': 'vim.fs',
         },
         'append_only': [
             'shared.lua',
diff --git a/test/functional/lua/fs_spec.lua b/test/functional/lua/fs_spec.lua
new file mode 100644
index 00000000000000..69eb8cd5392f2c
--- /dev/null
+++ b/test/functional/lua/fs_spec.lua
@@ -0,0 +1,33 @@
+local helpers = require('test.functional.helpers')(after_each)
+
+local clear = helpers.clear
+local exec_lua = helpers.exec_lua
+local eq = helpers.eq
+local mkdir_p = helpers.mkdir_p
+local rmdir = helpers.rmdir
+local nvim_dir = helpers.nvim_dir
+local test_build_dir = helpers.test_build_dir
+
+before_each(clear)
+
+describe('vim.fs', function()
+  describe('parents()', function()
+    it('works', function()
+      local test_dir = nvim_dir .. '/test'
+      mkdir_p(test_dir)
+      local dirs = exec_lua([[
+        local test_dir, test_build_dir = ...
+        local dirs = {}
+        for dir in vim.fs.parents(test_dir .. "/foo.txt") do
+          dirs[#dirs + 1] = dir
+          if dir == test_build_dir then
+            break
+          end
+        end
+        return dirs
+      ]], test_dir, test_build_dir)
+      eq({test_dir, nvim_dir, test_build_dir}, dirs)
+      rmdir(test_dir)
+    end)
+  end)
+end)

From c5526a27c3b61acb33b7c3c3fe518d8f1e0b602f Mon Sep 17 00:00:00 2001
From: Gregory Anders <greg@gpanders.com>
Date: Sun, 15 May 2022 19:53:23 -0600
Subject: [PATCH 2/6] feat(fs): add vim.fs.dirname()

---
 runtime/doc/lua.txt             |  9 +++++++++
 runtime/lua/vim/fs.lua          | 10 +++++++++-
 test/functional/lua/fs_spec.lua |  9 +++++++++
 3 files changed, 27 insertions(+), 1 deletion(-)

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 8f74dca4185c48..cf6d2e7276eacd 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2151,6 +2151,15 @@ set({mode}, {lhs}, {rhs}, {opts})                           *vim.keymap.set()*
 ==============================================================================
 Lua module: fs                                                        *lua-fs*
 
+dirname({file})                                             *vim.fs.dirname()*
+                Return the parent directory of the given file or directory
+
+                Parameters: ~
+                    {file}  (string) File or directory
+
+                Return: ~
+                    (string) Parent directory of {file}
+
 parents({start})                                            *vim.fs.parents()*
                 Iterate over all the parents of the given file or directory.
 
diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
index 08d2e495d2cc28..a3b7321cc9d1e9 100644
--- a/runtime/lua/vim/fs.lua
+++ b/runtime/lua/vim/fs.lua
@@ -21,7 +21,7 @@ local M = {}
 ---@return (function) Iterator
 function M.parents(start)
   return function(_, dir)
-    local parent = vim.fn.fnamemodify(dir, ":h")
+    local parent = M.dirname(dir)
     if parent == dir then
       return nil
     end
@@ -32,4 +32,12 @@ function M.parents(start)
     start
 end
 
+--- Return the parent directory of the given file or directory
+---
+---@param file (string) File or directory
+---@return (string) Parent directory of {file}
+function M.dirname(file)
+  return vim.fn.fnamemodify(file, ':h')
+end
+
 return M
diff --git a/test/functional/lua/fs_spec.lua b/test/functional/lua/fs_spec.lua
index 69eb8cd5392f2c..23ffb1e607fe7d 100644
--- a/test/functional/lua/fs_spec.lua
+++ b/test/functional/lua/fs_spec.lua
@@ -30,4 +30,13 @@ describe('vim.fs', function()
       rmdir(test_dir)
     end)
   end)
+
+  describe('dirname()', function()
+    it('works', function()
+      eq(test_build_dir, exec_lua([[
+        local nvim_dir = ...
+        return vim.fs.dirname(nvim_dir)
+      ]], nvim_dir))
+    end)
+  end)
 end)

From b740709431f5e68dac5238d455f9f86d5a564f36 Mon Sep 17 00:00:00 2001
From: Gregory Anders <greg@gpanders.com>
Date: Sun, 15 May 2022 19:55:18 -0600
Subject: [PATCH 3/6] feat(fs): add vim.fs.basename()

---
 runtime/doc/lua.txt             |  9 +++++++++
 runtime/lua/vim/fs.lua          |  8 ++++++++
 test/functional/lua/fs_spec.lua | 13 +++++++++++++
 3 files changed, 30 insertions(+)

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index cf6d2e7276eacd..bf30700fc0ac7a 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2151,6 +2151,15 @@ set({mode}, {lhs}, {rhs}, {opts})                           *vim.keymap.set()*
 ==============================================================================
 Lua module: fs                                                        *lua-fs*
 
+basename({file})                                           *vim.fs.basename()*
+                Return the basename of the given file or directory
+
+                Parameters: ~
+                    {file}  (string) File or directory
+
+                Return: ~
+                    (string) Basename of {file}
+
 dirname({file})                                             *vim.fs.dirname()*
                 Return the parent directory of the given file or directory
 
diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
index a3b7321cc9d1e9..29ce394a381cb9 100644
--- a/runtime/lua/vim/fs.lua
+++ b/runtime/lua/vim/fs.lua
@@ -40,4 +40,12 @@ function M.dirname(file)
   return vim.fn.fnamemodify(file, ':h')
 end
 
+--- Return the basename of the given file or directory
+---
+---@param file (string) File or directory
+---@return (string) Basename of {file}
+function M.basename(file)
+  return vim.fn.fnamemodify(file, ':t')
+end
+
 return M
diff --git a/test/functional/lua/fs_spec.lua b/test/functional/lua/fs_spec.lua
index 23ffb1e607fe7d..674a7f695701d6 100644
--- a/test/functional/lua/fs_spec.lua
+++ b/test/functional/lua/fs_spec.lua
@@ -7,6 +7,10 @@ local mkdir_p = helpers.mkdir_p
 local rmdir = helpers.rmdir
 local nvim_dir = helpers.nvim_dir
 local test_build_dir = helpers.test_build_dir
+local iswin = helpers.iswin
+local nvim_prog = helpers.nvim_prog
+
+local nvim_prog_basename = iswin() and 'nvim.exe' or 'nvim'
 
 before_each(clear)
 
@@ -39,4 +43,13 @@ describe('vim.fs', function()
       ]], nvim_dir))
     end)
   end)
+
+  describe('basename()', function()
+    it('works', function()
+      eq(nvim_prog_basename, exec_lua([[
+        local nvim_prog = ...
+        return vim.fs.basename(nvim_prog)
+      ]], nvim_prog))
+    end)
+  end)
 end)

From 2a62bec37ced51678ff914700d7165605d5a0d53 Mon Sep 17 00:00:00 2001
From: Gregory Anders <greg@gpanders.com>
Date: Sun, 15 May 2022 20:10:12 -0600
Subject: [PATCH 4/6] feat(fs): add vim.fs.dir()

This function is modeled after the path.dir() function from Penlight and
the luafilesystem module.
---
 runtime/doc/lua.txt             | 14 ++++++++++++++
 runtime/lua/vim/fs.lua          | 13 +++++++++++++
 test/functional/lua/fs_spec.lua | 14 ++++++++++++++
 3 files changed, 41 insertions(+)

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index bf30700fc0ac7a..5274b829b51055 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2160,6 +2160,20 @@ basename({file})                                           *vim.fs.basename()*
                 Return: ~
                     (string) Basename of {file}
 
+dir({path})                                                     *vim.fs.dir()*
+                Return an iterator over the files and directories located in
+                {path}
+
+                Parameters: ~
+                    {path}  (string) An absolute or relative path to the
+                            directory to iterate over
+
+                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".
+
 dirname({file})                                             *vim.fs.dirname()*
                 Return the parent directory of the given file or directory
 
diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
index 29ce394a381cb9..c28b06536b8931 100644
--- a/runtime/lua/vim/fs.lua
+++ b/runtime/lua/vim/fs.lua
@@ -48,4 +48,17 @@ function M.basename(file)
   return vim.fn.fnamemodify(file, ':t')
 end
 
+--- Return an iterator over the files and directories located in {path}
+---
+---@param path (string) An absolute or relative path to the directory to iterate
+---            over
+---@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".
+function M.dir(path)
+  return function(fs)
+    return vim.loop.fs_scandir_next(fs)
+  end, vim.loop.fs_scandir(path)
+end
+
 return M
diff --git a/test/functional/lua/fs_spec.lua b/test/functional/lua/fs_spec.lua
index 674a7f695701d6..6f1f1df0125b78 100644
--- a/test/functional/lua/fs_spec.lua
+++ b/test/functional/lua/fs_spec.lua
@@ -52,4 +52,18 @@ describe('vim.fs', function()
       ]], nvim_prog))
     end)
   end)
+
+  describe('dir()', function()
+    it('works', function()
+      eq(true, exec_lua([[
+        local dir, nvim = ...
+        for name, type in vim.fs.dir(dir) do
+          if name == nvim and type == 'file' then
+            return true
+          end
+        end
+        return false
+      ]], nvim_dir, nvim_prog_basename))
+    end)
+  end)
 end)

From f271d706611049bc53a6a439b310fe60bf0fab13 Mon Sep 17 00:00:00 2001
From: Gregory Anders <greg@gpanders.com>
Date: Sun, 15 May 2022 20:37:35 -0600
Subject: [PATCH 5/6] feat(fs): add vim.fs.find()

This is a pure Lua implementation of the Vim findfile() and finddir()
functions without the special syntax.
---
 runtime/doc/lua.txt             |  40 +++++++++++
 runtime/lua/vim/fs.lua          | 117 ++++++++++++++++++++++++++++++++
 test/functional/lua/fs_spec.lua |  13 ++++
 3 files changed, 170 insertions(+)

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 5274b829b51055..ba59c67446c156 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2183,6 +2183,46 @@ dirname({file})                                             *vim.fs.dirname()*
                 Return: ~
                     (string) Parent directory of {file}
 
+find({names}, {opts})                                          *vim.fs.find()*
+                Find files or directories 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 or only directories by specifying {type} to be "file"
+                or "directory", respectively.
+
+                Parameters: ~
+                    {names}  (string|table) Names of the files and directories
+                             to find. Must be base names, paths and globs are
+                             not supported.
+                    {opts}   (table) Optional keyword arguments:
+                             • path (string): Path to begin searching from. If
+                               omitted, the current working directory is used.
+                             • upward (boolean, default false): If true,
+                               search upward through parent directories.
+                               Otherwise, search through child 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 {name} 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) The paths of all matching files or directories
+
 parents({start})                                            *vim.fs.parents()*
                 Iterate over all the parents of the given file or directory.
 
diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
index c28b06536b8931..4519f2a1e42624 100644
--- a/runtime/lua/vim/fs.lua
+++ b/runtime/lua/vim/fs.lua
@@ -61,4 +61,121 @@ function M.dir(path)
   end, vim.loop.fs_scandir(path)
 end
 
+--- Find files or directories 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 or only directories by
+--- specifying {type} to be "file" or "directory", respectively.
+---
+---@param names (string|table) Names of the files and directories to find. Must
+---             be base names, paths and globs are not supported.
+---@param opts (table) Optional keyword arguments:
+---                       - path (string): Path to begin searching from. If
+---                              omitted, the current working directory is used.
+---                       - upward (boolean, default false): If true, search
+---                                upward through parent directories. Otherwise,
+---                                search through child 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 {name} 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) The paths of all matching files or directories
+function M.find(names, opts)
+  opts = opts or {}
+  vim.validate({
+    names = { names, { 's', 't' } },
+    path = { opts.path, 's', true },
+    upward = { opts.upward, 'b', true },
+    stop = { opts.stop, 's', true },
+    type = { opts.type, 's', true },
+    limit = { opts.limit, 'n', true },
+  })
+
+  names = type(names) == 'string' and { names } or names
+
+  local path = opts.path or vim.loop.cwd()
+  local stop = opts.stop
+  local limit = opts.limit or 1
+
+  local matches = {}
+
+  ---@private
+  local function add(match)
+    matches[#matches + 1] = match
+    if #matches == limit then
+      return true
+    end
+  end
+
+  if opts.upward then
+    ---@private
+    local function test(p)
+      local t = {}
+      for _, name in ipairs(names) do
+        local f = p .. '/' .. name
+        local stat = vim.loop.fs_stat(f)
+        if stat and (not opts.type or opts.type == stat.type) then
+          t[#t + 1] = f
+        end
+      end
+
+      return t
+    end
+
+    for _, match in ipairs(test(path)) do
+      if add(match) then
+        return matches
+      end
+    end
+
+    for parent in M.parents(path) do
+      if stop and parent == stop then
+        break
+      end
+
+      for _, match in ipairs(test(parent)) do
+        if add(match) then
+          return matches
+        end
+      end
+    end
+  else
+    local dirs = { path }
+    while #dirs > 0 do
+      local dir = table.remove(dirs, 1)
+      if stop and dir == stop then
+        break
+      end
+
+      for other, type in M.dir(dir) do
+        local f = dir .. '/' .. other
+        for _, name in ipairs(names) do
+          if name == other and (not opts.type or opts.type == type) then
+            if add(f) then
+              return matches
+            end
+          end
+        end
+
+        if type == 'directory' then
+          dirs[#dirs + 1] = f
+        end
+      end
+    end
+  end
+
+  return matches
+end
+
 return M
diff --git a/test/functional/lua/fs_spec.lua b/test/functional/lua/fs_spec.lua
index 6f1f1df0125b78..204bdc1567a3fe 100644
--- a/test/functional/lua/fs_spec.lua
+++ b/test/functional/lua/fs_spec.lua
@@ -66,4 +66,17 @@ describe('vim.fs', function()
       ]], nvim_dir, nvim_prog_basename))
     end)
   end)
+
+  describe('find()', function()
+    it('works', function()
+      eq({test_build_dir}, exec_lua([[
+        local dir = ...
+        return vim.fs.find('build', { path = dir, upward = true, type = 'directory' })
+      ]], nvim_dir))
+      eq({nvim_prog}, exec_lua([[
+        local dir, nvim = ...
+        return vim.fs.find(nvim, { path = dir, type = 'file' })
+      ]], test_build_dir, nvim_prog_basename))
+    end)
+  end)
 end)

From 046b4ed461cb78b8b302a6403cc7ea64ad6b6085 Mon Sep 17 00:00:00 2001
From: Gregory Anders <greg@gpanders.com>
Date: Tue, 17 May 2022 08:49:33 -0600
Subject: [PATCH 6/6] feat(fs): add vim.fs.normalize()

---
 runtime/doc/lua.txt             | 27 ++++++++++++++++++++++++++-
 runtime/lua/vim/fs.lua          | 28 ++++++++++++++++++++++++++--
 test/functional/lua/fs_spec.lua | 19 +++++++++++++++++++
 3 files changed, 71 insertions(+), 3 deletions(-)

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index ba59c67446c156..8a14f808568a14 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2166,7 +2166,8 @@ dir({path})                                                     *vim.fs.dir()*
 
                 Parameters: ~
                     {path}  (string) An absolute or relative path to the
-                            directory to iterate over
+                            directory to iterate over. The path is first
+                            normalized |vim.fs.normalize()|.
 
                 Return: ~
                     Iterator over files and directories in {path}. Each
@@ -2223,6 +2224,30 @@ find({names}, {opts})                                          *vim.fs.find()*
                 Return: ~
                     (table) The paths of all matching files or directories
 
+normalize({path})                                         *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 any backslash (\) characters are converted to
+                forward slashes (/). Environment variables are also expanded.
+
+                Example: >
+
+                 vim.fs.normalize('C:\Users\jdoe')
+                 => 'C:/Users/jdoe'
+
+                 vim.fs.normalize('~/src/neovim')
+                 => '/home/jdoe/src/neovim'
+
+                 vim.fs.normalize('$XDG_CONFIG_HOME/nvim/init.vim')
+                 => '/Users/jdoe/.config/nvim/init.vim'
+<
+
+                Parameters: ~
+                    {path}  (string) Path to normalize
+
+                Return: ~
+                    (string) Normalized path
+
 parents({start})                                            *vim.fs.parents()*
                 Iterate over all the parents of the given file or directory.
 
diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
index 4519f2a1e42624..9bf38f7bc329d8 100644
--- a/runtime/lua/vim/fs.lua
+++ b/runtime/lua/vim/fs.lua
@@ -51,14 +51,14 @@ end
 --- Return an iterator over the files and directories located in {path}
 ---
 ---@param path (string) An absolute or relative path to the directory to iterate
----            over
+---            over. The path is first normalized |vim.fs.normalize()|.
 ---@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".
 function M.dir(path)
   return function(fs)
     return vim.loop.fs_scandir_next(fs)
-  end, vim.loop.fs_scandir(path)
+  end, vim.loop.fs_scandir(M.normalize(path))
 end
 
 --- Find files or directories in the given path.
@@ -178,4 +178,28 @@ function M.find(names, opts)
   return matches
 end
 
+--- 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 any
+--- backslash (\\) characters are converted to forward slashes (/). Environment
+--- variables are also expanded.
+---
+--- Example:
+--- <pre>
+--- vim.fs.normalize('C:\\Users\\jdoe')
+--- => 'C:/Users/jdoe'
+---
+--- vim.fs.normalize('~/src/neovim')
+--- => '/home/jdoe/src/neovim'
+---
+--- vim.fs.normalize('$XDG_CONFIG_HOME/nvim/init.vim')
+--- => '/Users/jdoe/.config/nvim/init.vim'
+--- </pre>
+---
+---@param path (string) Path to normalize
+---@return (string) Normalized path
+function M.normalize(path)
+  vim.validate({ path = { path, 's' } })
+  return (path:gsub('^~/', vim.env.HOME .. '/'):gsub('%$([%w_]+)', vim.env):gsub('\\', '/'))
+end
+
 return M
diff --git a/test/functional/lua/fs_spec.lua b/test/functional/lua/fs_spec.lua
index 204bdc1567a3fe..2bcc84db0fddb3 100644
--- a/test/functional/lua/fs_spec.lua
+++ b/test/functional/lua/fs_spec.lua
@@ -79,4 +79,23 @@ describe('vim.fs', function()
       ]], test_build_dir, nvim_prog_basename))
     end)
   end)
+
+  describe('normalize()', function()
+    it('works with backward slashes', function()
+      eq('C:/Users/jdoe', exec_lua [[ return vim.fs.normalize('C:\\Users\\jdoe') ]])
+    end)
+    it('works with ~', function()
+      if iswin() then
+        pending([[$HOME does not exist on Windows ¯\_(ツ)_/¯]])
+      end
+      eq(os.getenv('HOME') .. '/src/foo', exec_lua [[ return vim.fs.normalize('~/src/foo') ]])
+    end)
+    it('works with environment variables', function()
+      local xdg_config_home = test_build_dir .. '/.config'
+      eq(xdg_config_home .. '/nvim', exec_lua([[
+        vim.env.XDG_CONFIG_HOME = ...
+        return vim.fs.normalize('$XDG_CONFIG_HOME/nvim')
+      ]], xdg_config_home))
+    end)
+  end)
 end)