Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/numtostr/fterm.nvim
:fire: No-nonsense floating terminal plugin for neovim :fire:
https://github.com/numtostr/fterm.nvim
floating lua neovim neovim-plugin nvim plugin terminal
Last synced: 13 days ago
JSON representation
:fire: No-nonsense floating terminal plugin for neovim :fire:
- Host: GitHub
- URL: https://github.com/numtostr/fterm.nvim
- Owner: numToStr
- License: mit
- Created: 2020-12-09T06:59:02.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2023-10-19T01:36:58.000Z (about 1 year ago)
- Last Synced: 2024-10-12T22:49:36.821Z (about 1 month ago)
- Topics: floating, lua, neovim, neovim-plugin, nvim, plugin, terminal
- Language: Lua
- Homepage:
- Size: 107 KB
- Stars: 745
- Watchers: 8
- Forks: 23
- Open Issues: 25
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
FTerm.nvim
🔥 No-nonsense floating terminal plugin for neovim 🔥
### 🚀 Installation
- With [packer.nvim](https://github.com/wbthomason/packer.nvim)
```lua
use "numToStr/FTerm.nvim"
```
- With [vim-plug](https://github.com/junegunn/vim-plug)
```vim
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()`.
```lua
require'FTerm'.setup({
border = 'double',
dimensions = {
height = 0.9,
width = 0.9,
},
})
-- Example keybindings
vim.keymap.set('n', '', 'lua require("FTerm").toggle()')
vim.keymap.set('t', '', 'lua require("FTerm").toggle()')
```
#### Configuration
Following options can be provided when calling [`setup()`](#setup). Below is the **default** configuration:
```lua
{
---Filetype of the terminal buffer
---@type string
ft = 'FTerm',
---Command to run inside the terminal
---NOTE: if given string[], it will skip the shell and directly executes the command
---@type fun():(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.
---@type boolean
auto_close = true,
---Highlight group for the terminal. See `:h winhl`
---@type string
hl = 'Normal',
---Transparency of the floating window. See `:h winblend`
---@type integer
blend = 0,
---Object containing the terminal window dimensions.
---The value for each field should be between `0` and `1`
---@type table
dimensions = {
height = 0.8, -- Height of the terminal window
width = 0.8, -- Width of the terminal window
x = 0.5, -- X axis of the terminal window
y = 0.5, -- Y axis of the terminal window
},
---Replace instead of extend the current environment with `env`.
---See `:h jobstart-options`
---@type boolean
clear_env = false,
---Map of environment variables extending the current environment.
---See `:h jobstart-options`
---@type table|nil
env = nil,
---Callback invoked when the terminal exits.
---See `:h jobstart-options`
---@type fun()|nil
on_exit = nil,
---Callback invoked when the terminal emits stdout data.
---See `:h jobstart-options`
---@type fun()|nil
on_stdout = nil,
---Callback invoked when the terminal emits stderr data.
---See `:h jobstart-options`
---@type fun()|nil
on_stderr = nil,
}
```
### 🔥 Usage
- Opening the terminal
```lua
require('FTerm').open()
-- or create a vim command
vim.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
```lua
require('FTerm').close()
-- or create a vim command
vim.api.nvim_create_user_command('FTermClose', require('FTerm').close, { bang = true })
```
- Exiting the terminal
> Unlike closing, this will remove the terminal session
```lua
require('FTerm').exit()
-- or create a vim command
vim.api.nvim_create_user_command('FTermExit', require('FTerm').exit, { bang = true })
```
- Toggling the terminal
```lua
require('FTerm').toggle()
-- or create a vim command
vim.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.
```lua
-- run() can take `string` or `table` just like `cmd` config
require('FTerm').run('man ls') -- with string
require('FTerm').run({'yarn', 'build'})
require('FTerm').run({'node', vim.api.nvim_get_current_buf()})
-- Or you can do this
vim.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](#configuration) as `setup()`. This uses [custom terminal](#custom-terminal) under the hood.
```lua
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 this
vim.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 terminal
local runners = { lua = 'lua', javascript = 'node' }
vim.keymap.set('n', '', function()
local buf = vim.api.nvim_buf_get_name(0)
local ftype = vim.filetype.match({ filename = buf })
local exec = runners[ftype]
if exec ~= nil then
require('FTerm').scratch({ cmd = { exec, buf } })
end
end)
```
### ✨ 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](#scratch-terminal).
Below are some examples:
- Running [gitui](https://github.com/extrawurst/gitui)
```lua
local fterm = require("FTerm")
local gitui = fterm:new({
ft = 'fterm_gitui', -- You can also override the default filetype, if you want
cmd = "gitui",
dimensions = {
height = 0.9,
width = 0.9
}
})
-- Use this to toggle gitui in a floating terminal
vim.keymap.set('n', '', function()
gitui:toggle()
end)
```
Screenshot
- Running [btop](https://github.com/aristocratos/btop)
```lua
local fterm = require("FTerm")
local btop = fterm:new({
ft = 'fterm_btop',
cmd = "btop"
})
-- Use this to toggle btop in a floating terminal
vim.keymap.set('n', '', function()
btop:toggle()
end)
```
Screenshot
### 💐 Credits
- [vim-floaterm](https://github.com/voldikss/vim-floaterm) for the inspiration