-1
Daily
5,622
stars
206
forks
21
watchers
193
prs
478
issues
12
releases
README
toggleterm.nvim
A neovim plugin to persist and toggle multiple terminals during an editing session
!toggleterm in action
Multiple orientations
- Float
!floating window
- Vertical
!vertical-terms
- Tab
!tab orientation
Send commands to different terminals
!exec
Winbar (Experimental/Nightly ONLY)
Requirements
This plugin only works in _Neovim 0.7_ or newer.
Installation
Using packer in lua
lua
use {"akinsho/toggleterm.nvim", tag = '', config = function()
require("toggleterm").setup()
end}
Using lazy.nvim in lua
lua
{
-- amongst your other plugins
{'akinsho/toggleterm.nvim', version = "", config = true}
-- or
{'akinsho/toggleterm.nvim', version = "", opts = {--[[ things you want to change go here]]}}
}
Using vim-plug in vimscript
vim
Plug 'akinsho/toggleterm.nvim', {'tag' : ''}
lua require("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 tag v1..
Notices
- 28/07/1990 — If using persist_mode terminal mappings should be changed to use wincmd instead otherwise persist mode will not work correctly. See here for details.
Why?
Neovim's terminal is a very cool, but not super ergonomic tool to use. I find that I often want to
set 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 I _really_ want these terminals to be easy to access.
I also want my terminal to look different from non-terminal buffers, so I use winhighlight to darken them based on the Normal
background colour.
This is the exact use case this was designed for. If that's your use case this might work for you.
Roadmap
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 a _pull request_ not an issue.
I'm also going to be pretty conservative about what I add.
Setup
This plugin must be explicitly enabled by using require("toggleterm").setup{}
Setting the open_mapping key to use for toggling the terminal(s) will set up mappings for _normal_ mode. The open_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 the insert_mappings key to true, the mapping will also take effect in insert mode; similarlyTop issues
#322[Bug] First hidden terminal is re-opened using {count}ToggleTerm command19 comments · 2022-09-23#452[Feature] Allow multiple terminals opened in different tabpages16 comments · 2023-07-01#425Copying and pasting visual selection to REPL9 comments · 2023-04-05#219Spawn terminal job using a list (and other jobstart() opts)8 comments · 2022-04-29#508Is it possible to include double quotes in the `cmd` argument?7 comments · 2023-11-09#260[Feature] Multiple terminals open in a container tab7 comments · 2022-07-08#621[BUG] Entering an existing terminal buffer does not trigger TermEnter event6 comments · 2024-11-13#374on_stderr function doesn't excute6 comments · 2022-12-20
Latest release
v2.13.1 v2.13.1 2024-12-302.13.1 (2024-12-27) Bug Fixes check for terminal win before check if is valid (622) (22aefd4), closes 435