Repository files navigation

Aneovim plugin to persist and toggle multiple terminals during an editing session

• Float

• Vertical

• Tab

This plugin only works inNeovim 0.7 or newer.

Usingpacker in lua

use {"akinsho/toggleterm.nvim",tag='*',config=function()require("toggleterm").setup()end}

Usinglazy.nvim in lua

{-- amongst your other plugins  {'akinsho/toggleterm.nvim',version="*",config=true}-- or  {'akinsho/toggleterm.nvim',version="*",opts= {--[[ things you want to change go here]]}}}

Usingvim-plug in vimscript

Plug'akinsho/toggleterm.nvim', {'tag' :'*'}luarequire("toggleterm").setup()

You can/should specify a tag for the current major version of the plugin, to avoid breaking changes as this plugin evolves.To use a version of this plugin compatible with nvim versions less than 0.7 please use the tagv1.*.

• 28/07/1990 — If usingpersist_mode terminal mappings should be changed to usewincmd instead otherwise persist mode will not work correctly. Seehere for details.

Neovim's terminal is a very cool, but not super ergonomic tool to use. I find that I often want toset a process going and leave it to continue to run in the background. I don't need to see it all the time.I just need to be able to refer back to it at intervals. I also sometimes want to create a new terminal and run a few commands.

Sometimes I want these side by side, and Ireally want these terminals to be easy to access.I also want my terminal to look different from non-terminal buffers, so I usewinhighlight to darken them based on theNormalbackground colour.

This is the exact use case this was designed for. If that's your use case this might work for you.

All I really want this plugin to be is what I described above. A wrapper around the terminal functionality.

It basically (almost) does all that I need it to.

I won't be turning this into a REPL plugin or doing a bunch of complex stuff.If you find any issues,please consider apull request not an issue.I'm also going to be pretty conservative about what I add.

This plugin must be explicitly enabled by usingrequire("toggleterm").setup{}

Setting theopen_mapping key to use for toggling the terminal(s) will set up mappings fornormal mode. Theopen_mapping can be a key string or an array of key strings.If you prefix the mapping with a number that particular terminal will be opened. Otherwise if a prefix is not set, then the last toggled terminal will be opened. In case there are multiple terminals opened they'll all be closed, and on the next mapping key they'll be restored.

If you set theinsert_mappings key totrue, the mapping will also take effect in insert mode; similarly settingterminal_mappings totrue will have the mappings take effect in the opened terminal.

However you will not be able to use a count with the open mapping in terminal and insert modes. You can create buffer specific mappings to exit terminal mode and then use a count with the open mapping. CheckTerminal window mappings for an example of how to do this.

alternatively you can do this manually (not recommended but, your prerogative)

" setautocmd TermEnterterm://*toggleterm#*\tnoremap<silent><c-t><Cmd>exe v:count1 . "ToggleTerm"<CR>" By applying the mappings this way you can pass a count to your" mapping to open a specific window." For example: 2<C-t> will open terminal 2nnoremap<silent><c-t><Cmd>exe v:count1 . "ToggleTerm"<CR>inoremap<silent><c-t><Esc><Cmd>exe v:count1 . "ToggleTerm"<CR>

NOTE: Please ensure you have sethidden in your neovim config, otherwise the terminals will be discarded when closed.

WARNING: Please do not copy and paste this configuration! It is here to show what options are available. It is not written to be used as is.

require("toggleterm").setup{-- size can be a number or function which is passed the current terminalsize=20 |function(term)ifterm.direction=="horizontal"thenreturn15elseifterm.direction=="vertical"thenreturnvim.o.columns*0.4endend,open_mapping=[[<c-\>]],-- or { [[<c-\>]], [[<c-¥>]] } if you also use a Japanese keyboard.on_create=fun(t:Terminal),-- function to run when the terminal is first createdon_open=fun(t:Terminal),-- function to run when the terminal openson_close=fun(t:Terminal),-- function to run when the terminal closeson_stdout=fun(t:Terminal,job:number,data:string[],name:string)-- callback for processing output on stdouton_stderr=fun(t:Terminal,job:number,data:string[],name:string)-- callback for processing output on stderron_exit=fun(t:Terminal,job:number,exit_code:number,name:string)-- function to run when terminal process exitshide_numbers=true,-- hide the number column in toggleterm buffersshade_filetypes= {},autochdir=false,-- when neovim changes it current directory the terminal will change it's own when next it's openedhighlights= {-- highlights which map to a highlight group name and a table of it's values-- NOTE: this is only a subset of values, any group placed here will be set for the terminal window splitNormal= {guibg="<VALUE-HERE>",    },NormalFloat= {link='Normal'    },FloatBorder= {guifg="<VALUE-HERE>",guibg="<VALUE-HERE>",    },  },shade_terminals=true,-- NOTE: this option takes priority over highlights specified so if you specify Normal highlights you should set this to falseshading_factor='<number>',-- the percentage by which to lighten dark terminal background, default: -30shading_ratio='<number>',-- the ratio of shading factor for light/dark terminal background, default: -3start_in_insert=true,insert_mappings=true,-- whether or not the open mapping applies in insert modeterminal_mappings=true,-- whether or not the open mapping applies in the opened terminalspersist_size=true,persist_mode=true,-- if set to true (default) the previous terminal mode will be remembereddirection='vertical'|'horizontal'|'tab'|'float',close_on_exit=true,-- close the terminal window when the process exitsclear_env=false,-- use only environmental variables from `env`, passed to jobstart()-- Change the default shell. Can be a string or a function returning a stringshell=vim.o.shell,auto_scroll=true,-- automatically scroll to the bottom on terminal output-- This field is only relevant if direction is set to 'float'float_opts= {-- The border key is *almost* the same as 'nvim_open_win'-- see :h nvim_open_win for details on borders however-- the 'curved' border is a custom border type-- not natively supported but implemented in this plugin.border='single'|'double'|'shadow'|'curved'|...otheroptionssupportedbywinopen-- like `size`, width, height, row, and col can be a number or function which is passed the current terminalwidth=<value>,height=<value>,row=<value>,col=<value>,winblend=3,zindex=<value>,title_pos='left'|'center'|'right',positionofthetitleofthefloatingwindow  },winbar= {enabled=false,name_formatter=function(term)--  term: Terminalreturnterm.nameend  },responsiveness= {-- breakpoint in terms of `vim.o.columns` at which terminals will start to stack on top of each other-- instead of next to each other-- default = 0 which means the feature is turned offhorizontal_breakpoint=135,  }}

This is the command the mappings call under the hood. You can use it directlyand prefix it with a count to target a specific terminal. This function also takesargumentssize,dir,direction andname. e.g.

:ToggleTerm size=40dir=~/Desktop direction=horizontal name=desktop

Ifdir is specified on creation toggle term will open at the specified directory.If the terminal has already been opened at a particular directory it will remain in that directory.

The directory can also be specified asgit_dir which toggleterm will thenuse to try and derive the git repo directory.NOTE: This will not work forgit-worktrees or other more complex setups.

Ifsize is specified, and the command opens a split (horizontal/vertical) terminal,the height/width of all terminals in the same direction will be changed tosize.

Ifdirection is specified, and the command opens a terminal,the terminal will be changed to the specified direction.

Ifname is specified, the display name is set for the toggled terminal. This name will be visiblewhen usingTermSelect command to indicate the specific terminal.

size anddirection are ignored if the command closes a terminal.

• Having multiple terminals with different directions open at the same time is unsupported.

This command allows you to open all the previously toggled terminal in one goor close all the open terminals at once.

This command allows you to open a terminal with a specific action.e.g.2TermExec cmd="git status" dir=~/<my-repo-path> will run git status in terminal 2.note that thecmd argumentmust be quoted.

NOTE: thedir argument can also beoptionally quoted if it contains spaces.

Thecmd anddir arguments can also expand the same special keywords as:h expand e.g.TermExec cmd="echo %" will be expanded toTermExec cmd="echo /file/example"

These special keywords can be escaped using the\ character, if you want to print character as is.

Thesize,direction andname arguments are like thesize,direction andname arguments ofToggleTerm.

By default, focus is returned to the original window after executing the command(except for floating terminals). Use argumentgo_back=0 to disable this behaviour.

You can send commands to a terminal without opening its window by using theopen=0 argument.

see:h expand() for more details

This command allows you to open a new terminal at the next available count.It's helpful in combination withTermSelect (see below) to work withterminals without needing to remember numbers. Thesize,dir,directionandname arguments work the same as inToggleTerm.

This command usesvim.ui.select to allow a user to select a terminal to openor to focus it if it's already open. This can be useful if you have a lot ofterminals and want to open a specific one.

You can "send lines" to the toggled terminals with the following commands:

• :ToggleTermSendCurrentLine <T_ID>: sends the whole line where you are standing with your cursor
• :ToggleTermSendVisualLines <T_ID>: sends all the (whole) lines in your visual selection
• :ToggleTermSendVisualSelection <T_ID>: sends only the visually selected text (this can be a block of text or a selection in a single line)

(<T_ID is an optional terminal ID parameter, which defines where should we send the lines.If the parameter is not provided, then the default is thefirst terminal)

Alternatively, for more fine-grained control and use in mappings, in lua:

localtrim_spaces=truevim.keymap.set("v","<space>s",function()require("toggleterm").send_lines_to_terminal("single_line",trim_spaces, {args=vim.v.count })end)-- Replace with these for the other two options-- require("toggleterm").send_lines_to_terminal("visual_lines", trim_spaces, { args = vim.v.count })-- require("toggleterm").send_lines_to_terminal("visual_selection", trim_spaces, { args = vim.v.count })-- For use as an operator map:-- Send motion to terminalvim.keymap.set("n",[[<leader><c-\>]],function()set_opfunc(function(motion_type)require("toggleterm").send_lines_to_terminal(motion_type,false, {args=vim.v.count })end)vim.api.nvim_feedkeys("g@","n",false)end)-- Double the command to send line to terminalvim.keymap.set("n",[[<leader><c-\><c-\>]],function()set_opfunc(function(motion_type)require("toggleterm").send_lines_to_terminal(motion_type,false, {args=vim.v.count })end)vim.api.nvim_feedkeys("g@_","n",false)end)-- Send whole filevim.keymap.set("n",[[<leader><leader><c-\>]],function()set_opfunc(function(motion_type)require("toggleterm").send_lines_to_terminal(motion_type,false, {args=vim.v.count })end)vim.api.nvim_feedkeys("ggg@G''","n",false)end)

Settrim_spaces=false for sending to REPLs for whitespace-sensitive languages like python.(For python, you probably want to start ipython withipython --no-autoindent.)

Example:

This function allows setting a display name for a terminal. This name is primarily used inside the winbar, and can be a more descriptive wayto remember, which terminal is for what.

You can map this to a key and call it with a count, which will then prompt you a name for the terminal with the matching ID.Alternatively you can call it with just the name e.g.:ToggleTermSetName work<CR> this will the prompt you for which terminal it should apply to.Lastly you can call it without any arguments, and it will prompt you for which terminal it should apply to then prompt you for the name to use.

This plugin automatically shades terminal filetypes to be darker than other windowyou can disable this by settingshade_terminals = false in the setup object

require'toggleterm'.setup {shade_terminals=false}

alternatively you can set,which filetypes should be shaded by setting

-- fzf is just an examplerequire'toggleterm'.setup {shade_filetypes= {"none","fzf"}}

setting"none" will allow normal terminal buffers to be highlighted.

By default, this plugin will persist the size of horizontal and vertical terminals.Split terminals in the same direction always have the same size.You can disable this behaviour by settingpersist_size = false in the setup object.Disabling this behaviour forces the opening terminal size to thesize defined in the setup object.

require'toggleterm'.setup{persist_size=false}

It can be helpful to add mappings to make moving in and out of a terminal easieronce toggled, whilst still keeping it open.

function_G.set_terminal_keymaps()localopts= {buffer=0}vim.keymap.set('t','<esc>',[[<C-\><C-n>]],opts)vim.keymap.set('t','jk',[[<C-\><C-n>]],opts)vim.keymap.set('t','<C-h>',[[<Cmd>wincmd h<CR>]],opts)vim.keymap.set('t','<C-j>',[[<Cmd>wincmd j<CR>]],opts)vim.keymap.set('t','<C-k>',[[<Cmd>wincmd k<CR>]],opts)vim.keymap.set('t','<C-l>',[[<Cmd>wincmd l<CR>]],opts)vim.keymap.set('t','<C-w>',[[<C-\><C-n><C-w>]],opts)end-- if you only want these mappings for toggle term use term://*toggleterm#* insteadvim.cmd('autocmd! TermOpen term://* lua set_terminal_keymaps()')

usinglazygit

Toggleterm also exposes theTerminal class so that this can be used to create custom terminalsfor showing terminal UIs likelazygit,htop etc.

Each terminal can take the following arguments:

Terminal:new {cmd=string-- command to execute when creating the terminal e.g. 'top'display_name=string-- the name of the terminaldirection=string-- the layout for the terminal, same as the main config optionsdir=string-- the directory for the terminalclose_on_exit=bool-- close the terminal window when the process exitshighlights=table-- a table with highlightsenv=table-- key:value table with environmental variables passed to jobstart()clear_env=bool-- use only environmental variables from `env`, passed to jobstart()on_open=fun(t:Terminal)-- function to run when the terminal openson_close=fun(t:Terminal)-- function to run when the terminal closesauto_scroll=boolean-- automatically scroll to the bottom on terminal output-- callbacks for processing the outputon_stdout=fun(t:Terminal,job:number,data:string[],name:string)-- callback for processing output on stdouton_stderr=fun(t:Terminal,job:number,data:string[],name:string)-- callback for processing output on stderron_exit=fun(t:Terminal,job:number,exit_code:number,name:string)-- function to run when terminal process exits}

If you want to spawn a custom terminal without running any command, you can omit thecmd option.

localTerminal=require('toggleterm.terminal').Terminallocallazygit=Terminal:new({cmd="lazygit",hidden=true })function_lazygit_toggle()lazygit:toggle()endvim.api.nvim_set_keymap("n","<leader>g","<cmd>lua _lazygit_toggle()<CR>", {noremap=true,silent=true})

This will create a new terminal, but the specified command is not being run immediately.The command will run once the terminal is opened. Alternativelyterm:spawn() can be usedto start the command in a background buffer without opening a terminal window yet. If thehidden key is set to true, this terminal will not be toggled by normal toggleterm commandssuch as:ToggleTerm or the open mapping. It will only open and close by using the returnedterminal object. A mapping for toggling the terminal can be set as in the example above.

Alternatively the terminal can be specified with a count, which is the number that can be usedto trigger this specific terminal. This can then be triggered using the current count e.g.:5ToggleTerm<CR>

locallazygit=Terminal:new({cmd="lazygit",count=5 })

You can also set a custom layout for a terminal.

locallazygit=Terminal:new({cmd="lazygit",dir="git_dir",direction="float",float_opts= {border="double",  },-- function to run on opening the terminalon_open=function(term)vim.cmd("startinsert!")vim.api.nvim_buf_set_keymap(term.bufnr,"n","q","<cmd>close<CR>", {noremap=true,silent=true})end,-- function to run on closing the terminalon_close=function(term)vim.cmd("startinsert!")end,})function_lazygit_toggle()lazygit:toggle()endvim.api.nvim_set_keymap("n","<leader>g","<cmd>lua _lazygit_toggle()<CR>", {noremap=true,silent=true})

WARNING: do not use any of the private functionality of the terminal or other non-public parts of the API as thesecan change in the future.

To tell each terminal apart you can use the terminal buffer variableb:toggle_numberin your statusline

" this is pseudo codeletstatusline.='%{&ft == "toggleterm" ? "terminal (".b:toggle_number.")" : ""}'

You can create your own commands by using the lua functions this plugin provides directly

command! -count=1 TermGitPushlua require'toggleterm'.exec("git push",<count>,12)command! -count=1 TermGitPushFlua require'toggleterm'.exec("git push -f",<count>,12)

In your first terminal, you need to leave theTERMINAL mode usingC-\C-N which can be remapped toEsc for ease of use.

Then you type on:2<C-\>, and the result:

Explain:

• 2: this is the terminal's number (or ID), your first terminal is1 (e.g. your 3rd terminal will be3<C-\>, so on).
• C-\: this is the combined key mapping to the command:ToggleTerm.

Please check out theWiki section on this topic.