NORMAL ~/wkd/p/terminal/help :set skin=modern utf-8

terminal.txt

Named, per-project terminals — terminal.nvim

doc/terminal.txt — rendered from the plugin's own vimdoc

*terminal.txt*  Named, per-project terminals                          *terminal.nvim*

CONTENTS *terminal-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-intro*

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 in

backend = "tmux" or "wezterm" picks a multiplexer; one that is not
available falls back to native with a notice. :Terminal pin restarts 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-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 *terminal-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 *terminal-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 *terminal-config*

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.

keys

j / k
next / previous line
gg / G
first / last line
⏎
open the line under the cursor
/
search plugins and apps (app: x or plugin: x narrows)
:
command line — Tab completes
:help x
vimdoc of a plugin (:e x = plugin page)
:ls · :apps · :play · :log · :stack
plugin list · app list · play area · activity stream · dependency graph
:log apps
the stream of one area (plugins or apps)
:colo x
colorscheme
:set skin=
modern | tui
?
this help
esc
close