feat(lua): vim.cmd() with kwargs acts like nvim_cmd() #18523

runtime/doc/lua.txt

@@ -1017,21 +1017,10 @@ vim.call({func}, {...})                                           *vim.call()*
         See also |vim.fn|.
         Equivalent to: >
             vim.fn[func]({...})
-<
+
-vim.cmd({cmd})                                                     *vim.cmd()*
+vim.cmd({command})
-        Executes multiple lines of Vimscript at once. It is an alias to
+        See |vim.cmd()|.
-        |nvim_exec()|, where `output` is set to false. Thus it works identical
+
-        to |:source|.
-        See also |ex-cmd-index|.
-        Example: >
-            vim.cmd('echo 42')
-            vim.cmd([[
-              augroup My_group
-                autocmd!
-                autocmd FileType c setlocal cindent
-              augroup END
-            ]])
-<
 vim.fn.{func}({...})                                                  *vim.fn*
         Invokes |vim-function| or |user-function| {func} with arguments {...}.
         To call autoload functions, use the syntax: >
@@ -1296,6 +1285,34 @@ vim.wo                                                                *vim.wo*
 ==============================================================================
 Lua module: vim                                                      *lua-vim*
 
+cmd({command})                                                     *vim.cmd()*
+                Execute Vim script commands.
+
+                Example: >
+
+                   vim.cmd('echo 42')
+                   vim.cmd([[
+                     augroup My_group
+                       autocmd!
+                       autocmd FileType c setlocal cindent
+                     augroup END
+                   ]])
+                   vim.cmd({ cmd = 'echo', args = { '"foo"' } })
+<
+
+                Parameters: ~
+                    {command}  string|table Command(s) to execute. If a
+                               string, executes multiple lines of Vim script
+                               at once. In this case, it is an alias to
+                               |nvim_exec()|, where `output` is set to false.
+                               Thus it works identical to |:source|. If a
+                               table, executes a single command. In this case,
+                               it is an alias to |nvim_cmd()| where `opts` is
+                               empty.
+
+                See also: ~
+                    |ex-cmd-index|
+
                                              *vim.connection_failure_errmsg()*
 connection_failure_errmsg({consequence})
                 TODO: Documentation

runtime/lua/vim/_editor.lua

@@ -284,9 +284,33 @@ vim.funcref = function(viml_func_name)
   return vim.fn[viml_func_name]
 end
 
--- An easier alias for commands.
+--- Execute Vim script commands.
-vim.cmd = function(command)
+---
-  return vim.api.nvim_exec(command, false)
+--- Example:
+--- <pre>
+---   vim.cmd('echo 42')
+---   vim.cmd([[
+---     augroup My_group
+---       autocmd!
+---       autocmd FileType c setlocal cindent
+---     augroup END
+---   ]])
+---   vim.cmd({ cmd = 'echo', args = { '"foo"' } })
+--- </pre>
+---
+---@param command string|table Command(s) to execute.
+---                            If a string, executes multiple lines of Vim script at once. In this
+---                            case, it is an alias to |nvim_exec()|, where `output` is set to
+---                            false. Thus it works identical to |:source|.
+---                            If a table, executes a single command. In this case, it is an alias
+---                            to |nvim_cmd()| where `opts` is empty.
+---@see |ex-cmd-index|
+function vim.cmd(command)
+  if type(command) == 'table' then
+    return vim.api.nvim_cmd(command, {})
+  else
+    return vim.api.nvim_exec(command, false)
+  end
 end
 
 -- These are the vim.env/v/g/o/bo/wo variable magic accessors.