docs: add tag `vim.fs.exists()` and document suggested replacement

2 files changed, 23 insertions, 0 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index cf53825c68..c3dddaf888 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -2926,6 +2926,17 @@ vim.keymap.set({mode}, {lhs}, {rhs}, {opts})                *vim.keymap.set()*
 ==============================================================================
 Lua module: vim.fs                                                    *vim.fs*
 
+
+                                                             *vim.fs.exists()*
+Use |uv.fs_stat()| to check a file's type, and whether it exists.
+
+Example: >lua
+  if vim.uv.fs_stat(file) then
+    vim.print("file exists")
+  end
+<
+
+
 vim.fs.basename({file})                                    *vim.fs.basename()*
     Return the basename of the given path
 
diff --git a/runtime/lua/vim/fs.lua b/runtime/lua/vim/fs.lua
index d91eeaf02f..2f007d97c3 100644
--- a/runtime/lua/vim/fs.lua
+++ b/runtime/lua/vim/fs.lua
@@ -1,3 +1,15 @@
+--- @brief <pre>help
+--- *vim.fs.exists()*
+--- Use |uv.fs_stat()| to check a file's type, and whether it exists.
+---
+--- Example:
+---
+--- >lua
+---   if vim.uv.fs_stat(file) then
+---     vim.print("file exists")
+---   end
+--- <
+
 local uv = vim.uv
 
 local M = {}