feat(lua): add traceback to vim.deprecate #18575

2 files changed, 16 insertions, 4 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 150a3d18e9..0b6b8d05ed 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1331,7 +1331,8 @@ defer_fn({fn}, {timeout})                                     *vim.defer_fn()*
                 Return: ~
                     timer luv timer object
 
-deprecate({name}, {alternative}, {version}, {plugin})        *vim.deprecate()*
+                                                             *vim.deprecate()*
+deprecate({name}, {alternative}, {version}, {plugin}, {backtrace})
                 Display a deprecation notification to the user.
 
                 Parameters: ~
@@ -1342,6 +1343,8 @@ deprecate({name}, {alternative}, {version}, {plugin})        *vim.deprecate()*
                                    function will be removed.
                     {plugin}       string|nil Plugin name that the function
                                    will be removed from. Defaults to "Nvim".
+                    {backtrace}    boolean|nil Prints backtrace. Defaults to
+                                   true.
 
 inspect({object}, {options})                                   *vim.inspect()*
                 Return a human-readable representation of the given object.
@@ -1379,6 +1382,9 @@ notify_once({msg}, {level}, {opts})                        *vim.notify_once()*
                     {opts}   (table|nil) Optional parameters. Unused by
                              default.
 
+                Return: ~
+                    (boolean) true if message was displayed, else false
+
 on_key({fn}, {ns_id})                                           *vim.on_key()*
                 Adds Lua function {fn} with namespace id {ns_id} as a listener
                 to every, yes every, input key.
diff --git a/runtime/lua/vim/_editor.lua b/runtime/lua/vim/_editor.lua
index 98921463b3..dc25d68f61 100644
--- a/runtime/lua/vim/_editor.lua
+++ b/runtime/lua/vim/_editor.lua
@@ -446,11 +446,14 @@ do
   ---@param msg string Content of the notification to show to the user.
   ---@param level number|nil One of the values from |vim.log.levels|.
   ---@param opts table|nil Optional parameters. Unused by default.
-  function vim.notify_once(msg, level, opts) -- luacheck: no unused args
+  ---@return boolean true if message was displayed, else false
+  function vim.notify_once(msg, level, opts)
     if not notified[msg] then
       vim.notify(msg, level, opts)
       notified[msg] = true
+      return true
     end
+    return false
   end
 end
 
@@ -784,12 +787,15 @@ end
 ---                              be removed.
 ---@param plugin      string|nil Plugin name that the function will be removed
 ---                              from. Defaults to "Nvim".
-function vim.deprecate(name, alternative, version, plugin)
+---@param backtrace   boolean|nil Prints backtrace. Defaults to true.
+function vim.deprecate(name, alternative, version, plugin, backtrace)
   local message = name .. ' is deprecated'
   plugin = plugin or 'Nvim'
   message = alternative and (message .. ', use ' .. alternative .. ' instead.') or message
   message = message .. ' See :h deprecated\nThis function will be removed in ' .. plugin .. ' version ' .. version
-  vim.notify_once(message, vim.log.levels.WARN)
+  if vim.notify_once(message, vim.log.levels.WARN) and backtrace ~= false then
+    vim.notify(debug.traceback('', 2):sub(2), vim.log.levels.WARN)
+  end
 end
 
 require('vim._meta')