feat: Add TermNew command

README.md

@@ -291,6 +291,13 @@ You can send commands to a terminal without opening its window by using the `ope
 
 see `:h expand()` for more details
 
+### TermNew
+
+This command allows you to open a new terminal at the next available count.
+It's helpful in combination with `TermSelect` (see below) to work with
+terminals without needing to remember numbers. The `size`, `dir`, `direction`
+and `name` arguments work the same as in `ToggleTerm`.
+
 ### TermSelect
 
 This command uses `vim.ui.select` to allow a user to select a terminal to open

doc/toggleterm.txt

@@ -292,6 +292,12 @@ You can send commands to a terminal without opening its window by using the
 
 see |expand()| for more details
 
+TERMNEW ~
+
+This command allows you to open a new terminal at the next available count.
+It's helpful in combination with `TermSelect` (see below) to work with
+terminals without needing to remember numbers. The `size`, `dir`, `direction`
+and `name` arguments work the same as in `ToggleTerm`.
 
 TERMSELECT ~
 

lua/toggleterm.lua

@@ -258,6 +258,18 @@ function M.send_lines_to_terminal(selection_type, trim_spaces, cmd_data)
   api.nvim_win_set_cursor(current_window, { start_line, start_col - 1 })
 end
 
+function M.new_command(args)
+  local parsed = commandline.parse(args)
+  vim.validate({
+    size = { parsed.size, "number", true },
+    dir = { parsed.dir, "string", true },
+    direction = { parsed.direction, "string", true },
+    name = { parsed.name, "string", true },
+  })
+  if parsed.size then parsed.size = tonumber(parsed.size) end
+  M.new(parsed.size, parsed.dir, parsed.direction, parsed.name)
+end
+
 function M.toggle_command(args, count)
   local parsed = commandline.parse(args)
   vim.validate({
@@ -278,6 +290,15 @@ function _G.___toggleterm_winbar_click(id)
   end
 end
 
+--- Creates new terminal at the first available id
+--- @param size number?
+--- @param dir string?
+--- @param direction string?
+--- @param name string?
+function M.new(size, dir, direction, name)
+  toggle_nth_term(terms.next_id(), size, dir, direction, name)
+end
+
 --- If a count is provided we operate on the specific terminal buffer
 --- i.e. 2ToggleTerm => open or close Term 2
 --- if the count is 1 we use a heuristic which is as follows
@@ -420,6 +441,12 @@ local function setup_commands()
     { count = true, complete = commandline.term_exec_complete, nargs = "*" }
   )
 
+  command(
+    "TermNew",
+    function(opts) M.new_command(opts.args) end,
+    { count = true, complete = commandline.toggle_term_complete, nargs = "*" }
+  )
+
   command(
     "ToggleTerm",
     function(opts) M.toggle_command(opts.args, opts.count) end,

lua/toggleterm/terminal.lua

@@ -106,7 +106,7 @@ local Terminal = {}
 --- hasn't already been allocated e.g. in a list of {1,2,5,6} the next id should
 --- be 3 then 4 then 7
 ---@return integer
-local function next_id()
+function M.next_id()
   local all = M.get_all(true)
   for index, term in pairs(all) do
     if index ~= term.id then return index end
@@ -205,7 +205,7 @@ function Terminal:new(term)
   self.__index = self
   term.newline_chr = term.newline_chr or get_newline_chr()
   term.direction = term.direction or conf.direction
-  term.id = id or next_id()
+  term.id = id or M.next_id()
   term.display_name = term.display_name
   term.float_opts = vim.tbl_deep_extend("keep", term.float_opts or {}, conf.float_opts)
   term.clear_env = vim.F.if_nil(term.clear_env, conf.clear_env)
@@ -228,7 +228,7 @@ end
 ---@package
 ---Add a terminal to the list of terminals
 function Terminal:__add()
-  if terminals[self.id] and terminals[self.id] ~= self then self.id = next_id() end
+  if terminals[self.id] and terminals[self.id] ~= self then self.id = M.next_id() end
   if not terminals[self.id] then terminals[self.id] = self end
   return self
 end
@@ -586,7 +586,7 @@ if _G.IS_TEST then
     end
   end
 
-  M.__next_id = next_id
+  M.__next_id = M.next_id
 end
 
 M.Terminal = Terminal