Nvim :help
pages, generated
from source
using the tree-sitter-vimdoc parser.
terminal-emulator
:edit term://bash
:vsplit term://top
autocmd VimEnter * ++nested split term://sh
term://{cwd}//{pid}:{cmd}
. This naming scheme is used
by :mksession to restore a terminal buffer (by restarting the {cmd}
).<C-\>
are sent to the underlying
program. If <C-\>
is pressed, the next key is sent unless it is <C-N>
or <C-O>
.
Use <C-\>
<C-N>
to return to normal mode. CTRL-\_CTRL-N
Use <C-\>
<C-O>
to execute one normal mode command and then return to terminal
mode. t_CTRL-\_CTRL-O
<Esc>
to exit terminal-mode::tnoremap <Esc> <C-\><C-n>
To simulate i_CTRL-R in terminal-mode::tnoremap <expr> <C-R> '<C-\><C-N>"'.nr2char(getchar()).'pi'
To use ALT+{h,j,k,l}
to navigate windows from any mode::tnoremap <A-h> <C-\><C-N><C-w>h
:tnoremap <A-j> <C-\><C-N><C-w>j
:tnoremap <A-k> <C-\><C-N><C-w>k
:tnoremap <A-l> <C-\><C-N><C-w>l
:inoremap <A-h> <C-\><C-N><C-w>h
:inoremap <A-j> <C-\><C-N><C-w>j
:inoremap <A-k> <C-\><C-N><C-w>k
:inoremap <A-l> <C-\><C-N><C-w>l
:nnoremap <A-h> <C-w>h
:nnoremap <A-j> <C-w>j
:nnoremap <A-k> <C-w>k
:nnoremap <A-l> <C-w>l
You can also create menus similar to terminal mode mappings, but you have to
use :tlmenu instead of :tmenu.au TermOpen * setlocal list
{g,b}:terminal_color_x
variables control the terminal color palette,
where x
is the color index between 0 and 15 inclusive. The variables are
read during TermOpen. The value must be a color name or hexadecimal string.
Example:let g:terminal_color_4 = '#ff0000'
let g:terminal_color_5 = 'green'
Only works for RGB UIs (see 'termguicolors'); for 256-color terminals the
color index is just forwarded.terminal-osc7
vim.api.nvim_create_autocmd({ 'TermRequest' }, {
desc = 'Handles OSC 7 dir change requests',
callback = function(ev)
if string.sub(vim.v.termrequest, 1, 4) == '\x1b]7;' then
local dir = string.gsub(vim.v.termrequest, '\x1b]7;file://[^/]*', '')
if vim.fn.isdirectory(dir) == 0 then
vim.notify('invalid dir: '..dir)
return
end
vim.api.nvim_buf_set_var(ev.buf, 'osc7_dir', dir)
if vim.o.autochdir and vim.api.nvim_get_current_buf() == ev.buf then
vim.cmd.cd(dir)
end
end
end
})
vim.api.nvim_create_autocmd({ 'BufEnter', 'WinEnter', 'DirChanged' }, {
callback = function(ev)
if vim.b.osc7_dir and vim.fn.isdirectory(vim.b.osc7_dir) == 1 then
vim.cmd.cd(vim.b.osc7_dir)
end
end
})
To try it out, select the above code and source it with :'<,'>lua
, then run
this command in a :terminal buffer:printf "\033]7;file://./foo/bar\033\\"OSC 52: write to system clipboard
terminal-osc52
printf '\033]52;;%s\033\\' "$(echo -n 'Hello world' | base64)"Nvim uses the configured clipboard provider to write to the system clipboard. Reading from the system clipboard with OSC 52 is not supported, as this would allow any arbitrary program in the :terminal to read the user's clipboard.
:autocmd TermOpen * setlocal statusline=%{b:term_title}
b:term_title
Terminal title (user-writable), typically displayed in the
window title or tab title of a graphical terminal emulator. Terminal
programs can set this by emitting an escape sequence.
autocmd TermClose * echom 'Terminal exited with status '..v:event.status
Use jobwait() to check if the terminal job has finished:let running = jobwait([&channel], 0)[0] == -1
==============================================================================
:Termdebug plugin terminal-debug
termdebug-starting
packadd termdebug
When loading the plugin from the vimrc file, add the "!" attribute:packadd! termdebug
:Termdebug
:Termdebug
or :TermdebugCommand
followed by the
command name, for example::Termdebug vim
This opens two windows::TermdebugCommand
:TermdebugCommand
command followed by the command name and
additional parameters.:TermdebugCommand vim --clean -c ':set nu'
Both the :Termdebug
and :TermdebugCommand
support an optional "!" bang
argument to start the command right away, without pausing at the gdb window
(and cursor will be in the debugged window). For example::TermdebugCommand! vim --clean
To attach gdb to an already running executable or use a core file, pass extra
arguments. E.g.::Termdebug vim core
:Termdebug vim 98343
If no argument is given, you'll end up in a gdb window, in which you need to
specify which command to run using e.g. the gdb file
command.termdebug-example
% makeStart Vim:
% ./vimLoad the termdebug plugin and start debugging Vim:
:packadd termdebug
:Termdebug vim
You should now have three windows:
source - where you started
gdb - you can type gdb commands here
program - the executed program will use this windowbreak ex_help runVim will start running in the program window. Put focus there and type:
:help gui
Gdb will run into the ex_help breakpoint. The source window now shows the
ex_cmds.c file. A red "1 " marker will appear in the signcolumn where the
breakpoint was set. The line where the debugger stopped is highlighted. You
can now step through the program. You will see the highlighting move as the
debugger executes a line of source code.print *eapIf mouse pointer movements are working, Vim will also show a balloon when the mouse rests on text that can be evaluated by gdb. You can also use the "K" mapping that will either use Nvim floating windows to show the results.
:BreakYou will see a "1" marker appear, this indicates the new breakpoint. Now run ":Cont" command and the code until the breakpoint will be executed.
watch curbufNow run ":Cont" (or type "cont" in the gdb window). Execution will now continue until the value of "curbuf" changes, which is in do_ecmd(). To remove this watchpoint again type in the gdb window:
delete 3You can see the stack by typing in the gdb window:
whereMove through the stack frames, e.g. with:
frame 3The source window will show the code, at the point where the call was made to a deeper level.
termdebug-stepping
CTRL-C
interrupt the program
:Run
:Arguments
In the window showing the source code these commands can be used to control
gdb:
:Run
[args] run the program with [args] or the previous arguments
:Arguments
{args}
set arguments for the next :Run
:Break
set a breakpoint at the cursor position
:Break {position}
set a breakpoint at the specified position
:Tbreak
set a temporary breakpoint at the cursor position
:Tbreak {position}
set a temporary breakpoint at the specified position
:Clear
delete the breakpoint at the cursor position:Step
execute the gdb "step" command
:Over
execute the gdb "next" command (:Next
is a Vim command)
:Until
execute the gdb "until" command
:Finish
execute the gdb "finish" command
:Continue
execute the gdb "continue" command
:Stop
interrupt the program:Clear
command if the cursor is in the line with the
breakpoint, or use the "Clear breakpoint" right-click menu entry.
termdebug-variables
:Evaluate
:Evaluate
evaluate the expression under the cursor
K
same (see termdebug_map_K to disable)
:Evaluate
{expr}
evaluate {expr}
:'<,'>Evaluate
evaluate the Visually selected text:Evaluate
to :Ev
.
The result is displayed in a floating window.
You can move the cursor to this window by running :Evaluate
(or K
) again.termdebug-frames
:Frame
:Up
:Down
:Frame
[frame] select frame [frame], which is a frame number,
address, or function name (default: current frame)
:Up
[count] go up [count] frames (default: 1; the frame that
called the current)
+
same (see termdebug_map_plus to disable)
:Down
[count] go down [count] frames (default: 1; the frame called
by the current)
-
same (see termdebug_map_minus to disable)termdebug-commands
:Gdb
jump to the gdb window
:Program
jump to the window with the running program
:Source
jump to the window with the source code, create it if there
isn't one
:Asm
jump to the window with the disassembly, create it if there
isn't one
:Var
jump to the window with the local and argument variables,
create it if there isn't one. This window updates whenever the
program is stoppedtermdebug-events
au User TermdebugStartPre echomsg 'debugging starting'
au User TermdebugStartPost echomsg 'debugging started'
au User TermdebugStopPre echomsg 'debugging stopping'
au User TermdebugStopPost echomsg 'debugging stopped'
TermdebugStartPre
TermdebugStartPost
:Termdebug
or
:TermdebugCommand
the event is triggered
before running the provided command in gdb.
TermdebugStopPre
TermdebugStopPost
termdebug-customizing
g:termdebug_config
In the past several global variables were used for configuration. These are
deprecated and using the g:termdebug_config dictionary is preferred. When
g:termdebug_config exists the other global variables will NOT be used.
The recommended way is to start with an empty dictionary:let g:termdebug_config = {}
Then you can add entries to the dictionary as mentioned below. The
deprecated global variable names are mentioned for completeness. If you are
switching over to using g:termdebug_config you can find the old variable name
and take over the value, then delete the deprecated variable.termdebug-prompt
<Esc>
, then you can move around in the buffer, copy/paste, etc.
Go back to editing the gdb command with any command that starts Insert mode,
such as a
or i
.
termdebug_use_prompt
let g:termdebug_config['use_prompt'] = 1
If there is no g:termdebug_config you can use:let g:termdebug_use_prompt = 1
termdebug_map_K
termdebug-mappings
The K key is normally mapped to :Evaluate unless a buffer local (:map-local)
mapping to K already exists. If you do not want this use:let g:termdebug_config['map_K'] = 0
If there is no g:termdebug_config you can use:let g:termdebug_map_K = 0
termdebug_map_minus
let g:termdebug_config['map_minus'] = 0
termdebug_map_plus
let g:termdebug_config['map_plus'] = 0
termdebug_disasm_window
let g:termdebug_config['disasm_window'] = 1
let g:termdebug_config['disasm_window_height'] = 15
If there is no g:termdebug_config you can use:let g:termdebug_disasm_window = 15
Any value greater than 1 will set the Asm window height to that value.
If the current window has enough horizontal space, it will be vertically split
and the Asm window will be shown side by side with the source code window (and
the height option won't be used).termdebug_variables_window
let g:termdebug_config['variables_window'] = 1
let g:termdebug_config['variables_window_height'] = 15
If there is no g:termdebug_config you can use:let g:termdebug_variables_window = 15
Any value greater than 1 will set the Var window height to that value.
If the current window has enough horizontal space, it will be vertically split
and the Var window will be shown side by side with the source code window (and
the height options won't be used).termdebug-communication
CTRL-C
can be used to
interrupt the running program. But after using the MI command
"-exec-continue" pressing CTRL-C
does not interrupt. Therefore you will see
"continue" being used for the :Continue
command, instead of using the
communication channel.g:termdebugger
:Termdebug
:let g:termdebug_config['command'] = "mygdb"
If there is no g:termdebug_config you can use:let g:termdebugger = "mygdb"
If the command needs an argument use a List:let g:termdebug_config['command'] = ['rr', 'replay', '--']
If there is no g:termdebug_config you can use:let g:termdebugger = ['rr', 'replay', '--']
If you are a mouse person, you can also define a mapping using your right
click to one of the terminal command like evaluate the variable under the
cursor:nnoremap <RightMouse> :Evaluate<CR>
or set/unset a breakpoint:nnoremap <RightMouse> :Break<CR>
Several arguments will be added to make gdb work well for the debugger.
If you want to modify them, add a function to filter the argument list:let g:termdebug_config['command_filter'] = MyDebugFilter
If you do not want the arguments to be added, but you do need to set the
"pty", use a function to add the necessary arguments:let g:termdebug_config['command_add_args'] = MyAddArguments
The function will be called with the list of arguments so far, and a second
argument that is the name of the pty.
gdb-version
hl-debugPC
hl-debugBreakpoint
The color of the signs can be adjusted with these highlight groups:
termdebug_shortcuts
map ,w :call TermDebugSendCommand('where')<CR>
The argument is the gdb command.termdebug_popup
:Break
Clear breakpoint :Clear
Evaluate :Evaluate
If you don't want this then disable it with:let g:termdebug_config['popup'] = 0
If there is no g:termdebug_config you can use:let g:termdebug_popup = 0
termdebug_signs
let g:termdebug_config['sign'] = '>>'
If there is no g:terminal_config yet you can use:let g:termdebug_config = {'sign': '>>'}
After this, breakpoints will be displayed as >>
in the signcolumn.termdebug_wide
let g:termdebug_config['wide'] = 163
If there is no g:termdebug_config you can use:let g:termdebug_wide = 163
This will set 'columns' to 163 when :Termdebug
is used. The value is
restored when quitting the debugger.