Add exclusive_layout option

When enabled, opening a terminal closes any other terminal currently
shown in the same layout.

Author: waiting-for-dev

CHANGELOG.md

@@ -4,6 +4,8 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+- Add `exclusive_layout` option (default `false`). When enabled, opening the terminal closes any other terminal currently shown in the same layout.
+
 ## 1.1.0 - 2026-02-05
 
 - Fix: Correctly center floating terminal when no borders are used.

README.md

@@ -70,6 +70,7 @@ require("ergoterm").setup({
 | `clear_env` | `boolean` | `false` | Clear environment variables before starting |
 | `cleanup_on_failure` | `boolean` | `false` | Cleanup terminal when process exits with non-zero code |
 | `cleanup_on_success` | `boolean` | `true` | Cleanup terminal when process exits with code 0 |
+| `exclusive_layout` | `boolean` | `false` | When this terminal opens, close any other terminal currently shown in the same layout (jobs are kept alive) |
 | `default_action` | `function` | `function(term) term:focus() end` | Action performed when selecting terminal with default picker action |
 | `fixed_height` | boolean | `true` | Keep the terminal height when new horizontal splits are opened (it depends on vim's `equalalways` being set) |
 | `fixed_width` | boolean | `true` | Keep the terminal width when new vertical splits are opened (it depends on vim's `equalalways` being set) |

doc/ergoterm.txt

@@ -416,6 +416,12 @@ default_action                                     *ergoterm-default_action*
     Default: `function(term) term:focus() end`
     Action performed when selecting terminal with default picker action
 
+exclusive_layout                               *ergoterm-exclusive_layout*
+    Type: `boolean`
+    Default: `false`
+    When this terminal opens, close any other terminal currently shown in the
+    same layout.
+
 fixed_height                                     *ergoterm-fixed_height*
     Type: `boolean`
     Default: `true`

lua/ergoterm/commandline.lua

@@ -56,6 +56,7 @@ end
 ---@field auto_list boolean?
 ---@field start_in_insert boolean?
 ---@field sticky boolean?
+---@field exclusive_layout boolean?
 ---@field cleanup_on_success boolean?
 ---@field cleanup_on_failure boolean?
 ---@field scrollback number?
@@ -109,6 +110,7 @@ function M.parse(args)
       auto_list = true,
       start_in_insert = true,
       sticky = true,
+      exclusive_layout = true,
       cleanup_on_success = true,
       cleanup_on_failure = true,
       show_on_success = true,
@@ -309,6 +311,8 @@ M._all_options = {
 
   sticky = M._boolean_options,
 
+  exclusive_layout = M._boolean_options,
+
   cleanup_on_success = M._boolean_options,
 
   cleanup_on_failure = M._boolean_options,
@@ -389,6 +393,7 @@ M._term_new_options = {
   ["env."] = M._all_options["env."],
   start_in_insert = M._all_options.start_in_insert,
   sticky = M._all_options.sticky,
+  exclusive_layout = M._all_options.exclusive_layout,
   cleanup_on_success = M._all_options.cleanup_on_success,
   cleanup_on_failure = M._all_options.cleanup_on_failure,
   scrollback = M._all_options.scrollback,
@@ -425,6 +430,7 @@ M._term_update_options = {
   auto_list = M._all_options.auto_list,
   start_in_insert = M._all_options.start_in_insert,
   sticky = M._all_options.sticky,
+  exclusive_layout = M._all_options.exclusive_layout,
   cleanup_on_success = M._all_options.cleanup_on_success,
   cleanup_on_failure = M._all_options.cleanup_on_failure,
   show_on_success = M._all_options.show_on_success,

lua/ergoterm/commands.lua

@@ -37,6 +37,7 @@ function M.new(args)
   vim.validate("cleanup_on_failure", parsed.cleanup_on_failure, "boolean", true)
   vim.validate("show_on_success", parsed.show_on_success, "boolean", true)
   vim.validate("show_on_failure", parsed.show_on_failure, "boolean", true)
+  vim.validate("exclusive_layout", parsed.exclusive_layout, "boolean", true)
   vim.validate("size", parsed.size, "table", true)
   vim.validate("float_opts", parsed.float_opts, "table", true)
   vim.validate("tags", parsed.tags, "table", true)
@@ -61,6 +62,7 @@ function M.new(args)
     cleanup_on_failure = parsed.cleanup_on_failure,
     show_on_success = parsed.show_on_success,
     show_on_failure = parsed.show_on_failure,
+    exclusive_layout = parsed.exclusive_layout,
     size = parsed.size,
     float_opts = parsed.float_opts,
     tags = parsed.tags,
@@ -188,6 +190,7 @@ function M.update(args, bang, picker)
   vim.validate("cleanup_on_failure", parsed.cleanup_on_failure, "boolean", true)
   vim.validate("show_on_success", parsed.show_on_success, "boolean", true)
   vim.validate("show_on_failure", parsed.show_on_failure, "boolean", true)
+  vim.validate("exclusive_layout", parsed.exclusive_layout, "boolean", true)
   vim.validate("size", parsed.size, "table", true)
   vim.validate("float_opts", parsed.float_opts, "table", true)
   vim.validate("tags", parsed.tags, "table", true)

lua/ergoterm/config.lua

@@ -77,6 +77,7 @@ M.NULL_CALLBACK = function(...) end
 ---@field size Size?
 ---@field start_in_insert boolean?
 ---@field sticky boolean?
+---@field exclusive_layout boolean?
 ---@field tags string[]?
 
 ---@class TerminalDefaults : TerminalDefaultsFromConfig
@@ -120,6 +121,7 @@ local config = {
     fixed_height = true,
     auto_list = true,
     sticky = false,
+    exclusive_layout = false,
     size = {
       below = "50%",
       above = "50%",

lua/ergoterm/instance.lua

@@ -85,6 +85,7 @@ local utils = require("ergoterm.utils")
 ---@field size Size
 ---@field start_in_insert boolean
 ---@field sticky boolean
+---@field exclusive_layout boolean
 ---@field name string
 ---@field on_close on_close
 ---@field on_focus on_focus
@@ -148,6 +149,7 @@ function Terminal:new(args)
   term.size = vim.tbl_deep_extend("keep", term.size or {}, config.get("terminal_defaults.size"))
   term.start_in_insert = vim.F.if_nil(term.start_in_insert, config.get("terminal_defaults.start_in_insert"))
   term.sticky = vim.F.if_nil(term.sticky, config.get("terminal_defaults.sticky"))
+  term.exclusive_layout = vim.F.if_nil(term.exclusive_layout, config.get("terminal_defaults.exclusive_layout"))
   term.on_close = vim.F.if_nil(term.on_close, config.get("terminal_defaults.on_close"))
   term.on_focus = vim.F.if_nil(term.on_focus, config.get("terminal_defaults.on_focus"))
   term.on_unfocus = vim.F.if_nil(term.on_unfocus, config.get("terminal_defaults.on_unfocus"))

lua/ergoterm/instance/open.lua

@@ -1,5 +1,7 @@
 ---@diagnostic disable: invisible
 
+---@module "ergoterm.collection"
+local collection = require("ergoterm.collection")
 ---@module "ergoterm.utils"
 local utils = require("ergoterm.utils")
 
@@ -36,6 +38,9 @@ end
 function M.show(term, layout)
   if not M.is_open(term) and term._state.bufnr and vim.api.nvim_buf_is_valid(term._state.bufnr) then
     layout = layout or term._state.layout
+    if term.exclusive_layout then
+      M._close_siblings_with_same_layout(term, layout)
+    end
     local window = nil
     if vim.tbl_contains(NEW_WINDOW_LAYOUTS, layout) then
       window = M._open_in_new_window(term, layout)
@@ -117,6 +122,17 @@ function M._set_float_options(term)
   vim.api.nvim_set_option_value("winblend", term.float_winblend, { scope = "local", win = window })
 end
 
+---@private
+function M._close_siblings_with_same_layout(term, layout)
+  for _, other in ipairs(collection.get_all()) do
+    if other ~= term
+        and other:is_open()
+        and other._state.layout == layout then
+      other:close()
+    end
+  end
+end
+
 return setmetatable(M, {
   __call = function(_, ...)
     return M.open(...)

lua/ergoterm/instance/update.lua

@@ -26,6 +26,7 @@ local ALLOWED_SETTINGS = {
   "size",
   "start_in_insert",
   "sticky",
+  "exclusive_layout",
   "on_close",
   "on_create",
   "on_focus",

spec/ergoterm/commandline_spec.lua

@@ -194,6 +194,7 @@ describe("commandline.term_new_complete", function()
     assert.is_true(vim.tbl_contains(result, "auto_list="))
     assert.is_true(vim.tbl_contains(result, "start_in_insert="))
     assert.is_true(vim.tbl_contains(result, "sticky="))
+    assert.is_true(vim.tbl_contains(result, "exclusive_layout="))
     assert.is_true(vim.tbl_contains(result, "cleanup_on_success="))
     assert.is_true(vim.tbl_contains(result, "cleanup_on_failure="))
     assert.is_true(vim.tbl_contains(result, "scrollback="))
@@ -263,6 +264,13 @@ describe("commandline.term_new_complete", function()
     assert.is_true(vim.tbl_contains(result, "sticky=false"))
   end)
 
+  it("completes boolean values for exclusive_layout", function()
+    local result = commandline.term_new_complete("exclusive_layout=", "exclusive_layout=", 16)
+
+    assert.is_true(vim.tbl_contains(result, "exclusive_layout=true"))
+    assert.is_true(vim.tbl_contains(result, "exclusive_layout=false"))
+  end)
+
   it("completes boolean values for cleanup_on_success", function()
     local result = commandline.term_new_complete("cleanup_on_success=", "cleanup_on_success=", 18)
 
@@ -322,6 +330,7 @@ describe("commandline.term_update_complete", function()
     assert.is_true(vim.tbl_contains(result, "auto_list="))
     assert.is_true(vim.tbl_contains(result, "start_in_insert="))
     assert.is_true(vim.tbl_contains(result, "sticky="))
+    assert.is_true(vim.tbl_contains(result, "exclusive_layout="))
     assert.is_true(vim.tbl_contains(result, "cleanup_on_success="))
     assert.is_true(vim.tbl_contains(result, "cleanup_on_failure="))
     assert.is_true(vim.tbl_contains(result, "show_on_success="))
@@ -339,6 +348,13 @@ describe("commandline.term_update_complete", function()
     assert.is_true(vim.tbl_contains(result, "tags="))
     assert.is_true(vim.tbl_contains(result, "meta.="))
   end)
+
+  it("completes boolean values for exclusive_layout", function()
+    local result = commandline.term_update_complete("exclusive_layout=", "exclusive_layout=", 16)
+
+    assert.is_true(vim.tbl_contains(result, "exclusive_layout=true"))
+    assert.is_true(vim.tbl_contains(result, "exclusive_layout=false"))
+  end)
 end)
 
 describe("commandline.term_inspect_complete", function()