doc/terminal.txt — rendered from the plugin's own vimdoc
*terminal.txt* Named, per-project terminals *terminal.nvim*
CONTENTS
1. Introduction ........................... |terminal-intro| 2. Commands ............................... |terminal-commands| 3. Lua API ................................ |terminal-api| 4. Keymaps ................................ |terminal-keymaps| 5. Configuration .......................... |terminal-config|
1. INTRODUCTION
terminal.nvim gives you named terminals per project root: a float, split, vsplit or tab that you toggle with one key, that keeps running while hidden, and that you can type into from buffers. It needs lib.nvim. The terminals live in a backend, the same API for all of them: native Neovim's own|:terminal|windows (the default) tmux panes of the tmux window Neovim runs in wezterm panes of the WezTerm window Neovim runs inbackend = "tmux"or"wezterm"picks a multiplexer; one that is not available falls back to native with a notice.:Terminal pinrestarts a native terminal as a pane so it outlives Neovim. Neovim also reports what it is doing (mode, file, branch, diagnostics) to tmux and WezTerm, and the window keys move on into the neighbouring pane at Neovim's edge. See docs/backends.md, docs/status.md and docs/navigation.md.
2. COMMANDS
*:Terminal* :Terminal Toggle the default terminal. :Terminal toggle [name] [--layout=] [--dir=] Focus / hide / show / create. :Terminal open [name] [--layout=] [--dir=] Show and focus; create when needed. --dir= a directory: the terminal belongs to its project, starts there and, without a name, is named after the folder (also on send and run). :Terminal hide [name] Close the window, keep the job. :Terminal close [name] Stop the job and remove the terminal. :Terminal pin [name] [--backend=] [--layout=] Restart a native terminal as a tmux/WezTerm pane so it outlives Neovim. Not a transfer: the old output is gone. :Terminal adopt [name] View a pane's screen in a read-only buffer. :Terminal repos Float: local state and CI of the repositories of the open terminals (see docs/repos.md). :Terminal list Pick one of this project's terminals (open, close, send a line). :Terminal cheat [shell] Cheatsheet of the shell the terminal runs (]] [[ pages, / searches, <CR> types the command, q closes). :Terminal send {line|file} [name] [--exec] :{range}Terminal send selection [name] [--exec] Type text into a terminal; --exec adds Enter. A characterwise selection sends exactly the selected characters, a blockwise one the block (made with $: every row to its own end) -- when the command line starts with the range '<,'> (or its alias "*"): ":" in Visual mode, typed by hand, or from a mapping that starts with ":" and keeps the range (":<C-u>" deletes it: write ":<C-u>'<,'>"). A linewise selection, a numeric range (:2,3) and a call without a command line (<Cmd> mapping, Lua) send whole lines. :Terminal run [--name=] [--layout=] [--direct] [--] {command...} Run a command in the "run" terminal. --direct starts it as the job itself.--layout=is float, split, vsplit or tab.--backend=is tmux or wezterm. <Tab> completes [name] from the terminals open in this project; toggle, open, send and --name= also offer the default name, the "run" name and the counts 1 to 9.
3. LUA API
local terminal = require("terminal")
terminal.setup(opts)
terminal.toggle({ name = "build", layout = "vsplit" })
terminal.open({ count = 3, focus = false })
terminal.open({ dir = "docs/api" }) the terminal of that folder
terminal.hide(target) terminal.close(target)
terminal.list(all)
terminal.names(all)
terminal.send(text, { newline = true, name = "repl" })
terminal.run({ "git", "status" })
terminal.run({ "make" }, { direct = true, on_exit = function(code) end })
terminal.navigate("h", 2)
terminal.pin({ name = "build" }, { backend = "tmux", layout = "vsplit" })
terminal.adopt({ name = "build" })
terminal.pick() the `:Terminal list` picker
terminal.cheatsheet() the `:Terminal cheat` window ({ shell = "bash" } forces a sheet)
terminal.summary() { count, visible, current } for a statusline
terminal.status()
terminal.teardown() close native terminals and adopt views, stop the status export until setup()
An argv list given to run() is quoted for the terminal's shell; a string is
typed as given.
*terminal-dir*
A target with dir (open, toggle, hide, close, send, run) names a directory:
the terminal belongs to the project of that directory (the git root above it;
without one the project the editor is in when the directory lies in it, else
the directory itself) and, when it is new, starts there. Without name
and count it is named after the folder, by its path below the project root
with a slash at the end (docs/api/; a folder main is "main/", not the
default terminal); the project root itself is the default terminal. So a
folder has one terminal, found again by the folder. It is its own, never a
cd typed into the project's terminal. A relative dir is read from the cwd;
what is not a directory makes the call fail, it is never replaced by the cwd.
*terminal-tree*
setup() registers the action terminal.here at lib.nvim.tree.registry:
"Terminal here". The own tree of filetree.nvim (adapter = "native") offers
it on every file and folder, in its context menu and its action list; it opens
the terminal of the node's folder (a file means the folder it lies in).
tree = { key = "<leader>t" } also puts it on a key in the tree buffer,
tree = false does not offer it.
names([all]) The names of this project's terminals (all projects with
all = true), straight from the registry: no multiplexer
is asked. Cheap enough for completion; list() is exact.
navigate(dir, count)
Move to the window in direction h, j, k or l (count
windows, default 1). At Neovim's edge the multiplexer
around it focuses the neighbouring pane; a floating window
never hands off. Raises on another direction or on a
count that is not a number from 0 up.
pin(target, opts) Restart a native terminal as a pane of tmux or WezTerm
(opts.backend, opts.layout) so it outlives Neovim.
adopt(target) Show a multiplexer terminal's screen in a read-only
buffer (a view, not a transfer); returns the buffer.
Failures come back as nil, err or false, err. open, toggle, send, run, pin
and adopt also show the message; hide and close only answer.
4. KEYMAPS
<A-h> normal, terminal toggle (a count picks terminal N)
<Esc> terminal leave terminal mode (<C-c> reaches the
shell: it is the interrupt, not a map)
<C-h/j/k> terminal window left/down/up; at Neovim's edge
the multiplexer focuses the next pane
window_right terminal (off) so <C-l> clears in the shell
clear terminal (off) types "cls" for cmd.exe and
PowerShell, "clear" for any other shell
(the terminal's shell decides, not the
OS)
nav_* normal (off) the same moves from Normal mode:
nav_left/down/up/right, with a count
cheatsheet normal, terminal (off) open the cheatsheet of the shell
Move one with keymaps = { toggle = "<A-x>" }, drop one with false, bind
nothing with preset = false.
5. CONFIGURATION
See docs/configuration.md for every option and its default.
*terminal-sessions*
With sessions.nvim a session saves the definitions of the project's native
terminals (name, layout, directory, and the command of a run with direct
with its close, title and float) in .<session>.terminals.json beside
the session file and reopens them, hidden, when it is loaded, each in the
directory it was started in (a terminal opened for a folder comes back in that
folder). A shell whose directory is gone opens in the project's directory, with
a warning; a command whose directory is gone is not started. With
sessions.nvim's relative_paths a directory inside the project is saved
relative to the session root and comes back below the root of the load (a
moved checkout, another machine); root_remap translates the absolute ones.
No process is saved. Terminals that already exist are left alone. The commands are asked about once (sessions.commands: "ask",
"run" or "never"); sessions.enable = false turns it off. A terminal started
by run() with { direct = true, session = false } is never saved. See
docs/sessions.md.