FTerm.nvim

^{🔥 No-nonsense floating terminal plugin for neovim 🔥}

🚀 Installation

• With packer.nvim

use"numToStr/FTerm.nvim"

• With vim-plug

Plug 'numToStr/FTerm.nvim'

⚒️ Setup (optional)

FTerm default terminal has sane defaults. If you want to use the default configuration then you don't have to do anything but you can override the default configuration by calling setup().

require'FTerm'.setup({
border='double',
dimensions= {
height=0.9,
width=0.9,
},
})
-- Example keybindingsvim.keymap.set('n', '<A-i>', '<CMD>lua require("FTerm").toggle()<CR>')
vim.keymap.set('t', '<A-i>', '<C-\\><C-n><CMD>lua require("FTerm").toggle()<CR>')

Configuration

Following options can be provided when calling setup(). Below is the default configuration:

{
---Filetype of the terminal buffer---@typestringft='FTerm',
---Command to run inside the terminal---NOTE: if given string[], it will skip the shell and directly executes the command---@typefun():(string|string[])|string|string[]cmd=os.getenv('SHELL'),
---Neovim's native window border. See `:h nvim_open_win` for more configuration options.border='single',
---Close the terminal as soon as shell/command exits.---Disabling this will mimic the native terminal behaviour.---@typebooleanauto_close=true,
---Highlight group for the terminal. See `:h winhl`---@typestringhl='Normal',
---Transparency of the floating window. See `:h winblend`---@typeintegerblend=0,
---Object containing the terminal window dimensions.---The value for each field should be between `0` and `1`---@typetable<string,number>dimensions= {
height=0.8, -- Height of the terminal windowwidth=0.8, -- Width of the terminal windowx=0.5, -- X axis of the terminal windowy=0.5, -- Y axis of the terminal window
},
---Replace instead of extend the current environment with `env`.---See `:h jobstart-options`---@typebooleanclear_env=false,
---Map of environment variables extending the current environment.---See `:h jobstart-options`---@typetable<string,string>|nilenv=nil,
---Callback invoked when the terminal exits.---See `:h jobstart-options`---@typefun()|nilon_exit=nil,
---Callback invoked when the terminal emits stdout data.---See `:h jobstart-options`---@typefun()|nilon_stdout=nil,
---Callback invoked when the terminal emits stderr data.---See `:h jobstart-options`---@typefun()|nilon_stderr=nil,
}

🔥 Usage

• Opening the terminal

require('FTerm').open()
-- or create a vim commandvim.api.nvim_create_user_command('FTermOpen', require('FTerm').open, { bang=true })

• Closing the terminal

This will close the terminal window but preserves the actual terminal session

require('FTerm').close()
-- or create a vim commandvim.api.nvim_create_user_command('FTermClose', require('FTerm').close, { bang=true })

• Exiting the terminal

Unlike closing, this will remove the terminal session

require('FTerm').exit()
-- or create a vim commandvim.api.nvim_create_user_command('FTermExit', require('FTerm').exit, { bang=true })

• Toggling the terminal

require('FTerm').toggle()
-- or create a vim commandvim.api.nvim_create_user_command('FTermToggle', require('FTerm').toggle, { bang=true })

• Running commands

If you want to run some commands, you can do that by using the run method. This method uses the default terminal and doesn't override the default command (which is usually your shell). Because of this when the command finishes/exits, the terminal won't close automatically.

-- run() can take `string` or `table` just like `cmd` configrequire('FTerm').run('man ls') -- with stringrequire('FTerm').run({'yarn', 'build'})
require('FTerm').run({'node', vim.api.nvim_get_current_buf()})
-- Or you can do thisvim.api.nvim_create_user_command('ManLs', function()
require('FTerm').run('man ls')
end, { bang=true })
vim.api.nvim_create_user_command('YarnBuild', function()
require('FTerm').run({'yarn', 'build'})
end, { bang=true })

⚡ Scratch Terminal

You can also create scratch terminal for ephemeral processes like build commands. Scratch terminal will be created when you can invoke it and will be destroyed when the command exits. You can use the scratch({config}) method to create it which takes same options as setup(). This uses custom terminal under the hood.

require('FTerm').scratch({ cmd='yarn build' })
require('FTerm').scratch({ cmd= {'cargo', 'build', '--target', os.getenv('RUST_TARGET')} })
-- Scratch terminals are awesome because you can do thisvim.api.nvim_create_user_command('YarnBuild', function()
require('FTerm').scratch({ cmd= {'yarn', 'build'} })
end, { bang=true })
vim.api.nvim_create_user_command('CargoBuild', function()
require('FTerm').scratch({ cmd= {'cargo', 'build', '--target', os.getenv("RUST_TARGET")} })
end, { bang=true })
-- Code Runner - execute commands in a floating terminallocalrunners= { lua='lua', javascript='node' }
vim.keymap.set('n', '<leader><Enter>', function()
localbuf=vim.api.nvim_buf_get_name(0)
localftype=vim.filetype.match({ filename=buf })
localexec=runners[ftype]
ifexec~=nilthenrequire('FTerm').scratch({ cmd= { exec, buf } })
endend)

✨ Custom Terminal

By default FTerm only creates and manage one terminal instance but you can create your terminal by using the FTerm:new() function and overriding the default command. This is useful if you want a separate terminal and the command you want to run is a long-running process. If not, see scratch terminal.

Below are some examples:

• Running gitui

localfterm=require("FTerm")
localgitui=fterm:new({
ft='fterm_gitui', -- You can also override the default filetype, if you wantcmd="gitui",
dimensions= {
height=0.9,
width=0.9
}
})
-- Use this to toggle gitui in a floating terminalvim.keymap.set('n', '<A-g>', function()
gitui:toggle()
end)

Screenshot

• Running btop

localfterm=require("FTerm")
localbtop=fterm:new({
ft='fterm_btop',
cmd="btop"
})
-- Use this to toggle btop in a floating terminalvim.keymap.set('n', '<A-b>', function()
btop:toggle()
end)

Screenshot

💐 Credits

• vim-floaterm for the inspiration