Terman.nvim

Simple terminal session management

Features

• Run terminal jobs in a buffer you can hide
• Preset or arbitrary terminal jobs
• Customisable with user defined functions to run before/after a job
• Floating or split pane
• Compatible with linux, maybe macOS and definitely not windows

Usage

• :Terman will run the preset or terminal command you pass in, preferring to run presets if there is a name clash.
• :TermanRun will allow you to run any command and view its output in a persistent window.

You can also call open() and pass in an existing or new preset. Presets can be searched with get_session_preset() by passing in the name of the session (or cmd if no name was provided).

It is recommended to bind your presets to :Terman YourPreset

When in a terminal, <esc><esc> will hide the window.

Installation

Lazy.nvim:

{
  'Panama0/Terman.nvim',
  opts = {}
}

Vim.pack (0.12)

vim.pack.add({
  "https://github.com/Panama0/Terman.nvim"
})

Config

Below is the default config:

local config = {
	presets = {
		{
			name = "Terminal",
		},
	},
	window_options = {
		floating_width = 0.8,
		floating_height = 0.8,
		split_height = 0.2,
		navigate_up = "<C-k>",
		navigate_down = "<C-j>",
	},
}

Add as many presets as you like using the below fields:

---@class terman.WindowOptions
---@field floating_width number Width of floating windows
---@field floating_height number Height of floating windows
---@field split_height number Height of split windows
---@field navigate_up string Keybind to navigate up from terman windows (terminal mode)
---@field navigate_down string Keybind to navigate down from terman windows (terminal mode)

---@class terman.Preset
---@field name string? Name that can be used to retrieve the session
---@field cmd string? Command to run
---@field on_exit function? Function to run on command exit, exit code is passed in
---@field pre_open function? Function to run once upon session creation
---@field pos? 'floating' | 'top' | 'bottom' Window position, default floating
---@field persist? boolean if true, terminal will stay open after job completion

---@class terman.Config
---@field presets terman.Preset[]
---@field window_options terman.WindowOptions

Examples

Using on_exit and pre_open callbacks to open a chosen file with Yazi:

config = function()
  local function setup_yazi()
    local yazi_dir = vim.fn.stdpath 'data' .. '/yazi'
    local file = yazi_dir .. '/chooser-file.txt'

    -- make file if not there
    if vim.fn.isdirectory(yazi_dir) == 0 then
      vim.fn.mkdir(yazi_dir, 'p')
    end
    local f = io.open(file, 'w')
    f:close()
  end

  local function open_chooser_file()
    local yazi_dir = vim.fn.stdpath 'data' .. '/yazi'
    local file = yazi_dir .. '/chooser-file.txt'

    local f = io.open(file, 'r')
    chosenFile = f:read '*l'
    f:close()

    if chosenFile then
      vim.cmd('e ' .. chosenFile)
    end
  end

  local opts = {
    presets = {
      {
        name = 'Yazi',
        cmd = 'yazi --chooser-file ~/.local/share/nvim/yazi/chooser-file.txt',
        pre_open = setup_yazi,
        on_exit = open_chooser_file,
      },
    },
  }

  require('terman').setup(opts)
end

Lazy Loading

It is recommended to lazy load using keys if using lazy.nvim

{
  'Panama0/Terman.nvim',
  keys = {
    { '<leader>oy', '<cmd>Terman Yazi<CR>', desc = '[o]pen [y]azi' },
  },
  opts = {},
}