Add scrollback setting to configure terminal scrollback buffer size

Author: waiting-for-dev

CHANGELOG.md

@@ -6,6 +6,7 @@ All notable changes to this project will be documented in this file.
 
 - BREAKING: `selectable` option has been deprecated in favor of `auto_list`.
 - BREAKING: Rename `.get_last_focused()` to `.get_target_for_bang()`.
+- Added `scrollback` setting to configure terminal scrollback buffer size.
 
 ## 0.9.0 - 2025-11-07
 

README.md

@@ -267,6 +267,7 @@ All options default to values from your configuration:
 - `clear_env` - Use clean environment for the job
 - `cleanup_on_success` - Cleanup terminal when process exits successfully (exit code 0)
 - `cleanup_on_failure` - Cleanup terminal when process exits with failure (exit code non-zero)
+- `scrollback` - Number of lines to keep in scrollback buffer.
 - `show_on_success` - Open terminal window when process exits successfully (exit code 0). Requires `cleanup_on_success` to be `false`.
 - `show_on_failure` - Open terminal window when process exits with failure (exit code non-zero). Requires `cleanup_on_failure` to be `false`.
 - `default_action` - Function to invoke when selecting terminal in picker with `<Enter>`

doc/ergoterm.txt

@@ -371,6 +371,13 @@ terminal_defaults.cleanup_on_failure ~
 
     Close terminal window when the job process exits with failure (exit code non-zero).
 
+                                                      *ergoterm-scrollback*
+terminal_defaults.scrollback ~
+    Default: `vim.o.scrollback`
+    Type: `number`
+
+    Number of lines to keep in terminal scrollback buffer.
+
                                                       *ergoterm-show_on_success*
 terminal_defaults.show_on_success ~
     Default: `false`

lua/ergoterm/commandline.lua

@@ -54,6 +54,7 @@ end
 ---@field sticky boolean?
 ---@field cleanup_on_success boolean?
 ---@field cleanup_on_failure boolean?
+---@field scrollback number?
 ---@field show_on_success boolean?
 ---@field show_on_failure boolean?
 ---@field text string?
@@ -298,6 +299,8 @@ M._all_options = {
 
   cleanup_on_failure = M._boolean_options,
 
+  scrollback = function() return {} end,
+
   show_on_success = M._boolean_options,
 
   show_on_failure = M._boolean_options,
@@ -369,6 +372,7 @@ M._term_new_options = {
   sticky = M._all_options.sticky,
   cleanup_on_success = M._all_options.cleanup_on_success,
   cleanup_on_failure = M._all_options.cleanup_on_failure,
+  scrollback = M._all_options.scrollback,
   show_on_success = M._all_options.show_on_success,
   show_on_failure = M._all_options.show_on_failure,
   ["size.below"] = M._all_options["size.below"],

lua/ergoterm/commands.lua

@@ -145,8 +145,7 @@ end
 ---Updates terminal configuration after creation
 ---
 ---Allows modification of terminal settings without recreating the terminal.
----Updatable fields include layout, name, auto_scroll, persist_mode, persist_size,
----auto_list, and start_in_insert. Changes take effect immediately.
+---Use autocompletion to see which settings can be updated.
 ---
 ---Bang mode (!) targets the last focused terminal directly.
 ---Target option selects a terminal by name.

lua/ergoterm/config.lua

@@ -66,6 +66,7 @@ M.NULL_CALLBACK = function(...) end
 ---@field on_open on_open?
 ---@field on_stop on_stop?
 ---@field on_start on_start?
+---@field scrollback number?
 ---@field show_on_success boolean?
 ---@field show_on_failure boolean?
 ---@field persist_mode boolean?
@@ -130,6 +131,7 @@ local config = {
     on_start = M.NULL_CALLBACK,
     on_job_stderr = M.NULL_CALLBACK,
     on_job_stdout = M.NULL_CALLBACK,
+    scrollback = vim.o.scrollback,
     show_on_success = false,
     show_on_failure = false,
     shell = vim.o.shell,

lua/ergoterm/instance.lua

@@ -93,6 +93,7 @@ local utils = require("ergoterm.utils")
 ---@field on_open on_open
 ---@field on_start on_start
 ---@field on_stop on_stop
+---@field scrollback number
 ---@field show_on_success boolean
 ---@field show_on_failure boolean
 ---@field tags string[]
@@ -152,6 +153,7 @@ function Terminal:new(args)
   term.on_open = vim.F.if_nil(term.on_open, config.get("terminal_defaults.on_open"))
   term.on_start = vim.F.if_nil(term.on_start, config.get("terminal_defaults.on_start"))
   term.on_stop = vim.F.if_nil(term.on_stop, config.get("terminal_defaults.on_stop"))
+  term.scrollback = term.scrollback or config.get("terminal_defaults.scrollback")
   term.show_on_success = vim.F.if_nil(term.show_on_success, config.get("terminal_defaults.show_on_success"))
   term.show_on_failure = vim.F.if_nil(term.show_on_failure, config.get("terminal_defaults.show_on_failure"))
   term.tags = term.tags or vim.tbl_deep_extend("keep", {}, config.get("terminal_defaults.tags") or {})

lua/ergoterm/instance/start.lua

@@ -17,11 +17,11 @@ function M.start(term)
     term._state.dir = term:_compute_dir()
     term._state.bufnr = vim.api.nvim_create_buf(false, false)
     term._state.has_been_started = true
+    M._set_buffer_options(term)
     vim.api.nvim_buf_call(term._state.bufnr, function()
       term._state.job_id = M._start_job(term)
     end)
     M._setup_buffer_autocommands(term)
-    M._set_buffer_options(term)
     term:on_start()
   end
   return term
@@ -74,6 +74,7 @@ function M._set_buffer_options(term)
   vim.api.nvim_set_option_value("filetype", FILETYPE, { scope = "local", buf = bufnr })
   vim.api.nvim_set_option_value("buflisted", false, { scope = "local", buf = bufnr })
   vim.api.nvim_set_option_value("bufhidden", "hide", { scope = "local", buf = bufnr })
+  vim.api.nvim_set_option_value("scrollback", term.scrollback, { scope = "local", buf = bufnr })
 end
 
 return setmetatable(M, {

spec/ergoterm/commandline_spec.lua

@@ -181,6 +181,9 @@ describe("commandline.term_new_complete", function()
     assert.is_true(vim.tbl_contains(result, "sticky="))
     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="))
+    assert.is_true(vim.tbl_contains(result, "show_on_success="))
+    assert.is_true(vim.tbl_contains(result, "show_on_failure="))
     assert.is_true(vim.tbl_contains(result, "size.below="))
     assert.is_true(vim.tbl_contains(result, "size.above="))
     assert.is_true(vim.tbl_contains(result, "size.left="))

spec/ergoterm/instance/start_spec.lua

@@ -154,6 +154,14 @@ describe(".start", function()
     assert.equal("hide", vim.bo[term:get_state("bufnr")].bufhidden)
   end)
 
+  it("sets the buffer scrollback from term's setting", function()
+    local term = Terminal:new({ scrollback = 5000 })
+
+    start(term)
+
+    assert.equal(5000, vim.bo[term:get_state("bufnr")].scrollback)
+  end)
+
   it("does nothing if already started", function()
     local term = Terminal:new()
     start(term)