• Stars
    star
    605
  • Rank 74,072 (Top 2 %)
  • Language
    Lua
  • License
    MIT License
  • Created almost 4 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

πŸ”₯ No-nonsense floating terminal plugin for neovim πŸ”₯

FTerm.nvim

πŸ”₯ No-nonsense floating terminal plugin for neovim πŸ”₯

FTerm

πŸš€ Installation

use "numToStr/FTerm.nvim"
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 keybindings
vim.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
    ---@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<string,number>
    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<string,string>|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
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

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

require('FTerm').exit()

-- or create a vim command
vim.api.nvim_create_user_command('FTermExit', require('FTerm').exit, { bang = true })
  • Toggling the terminal
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.

-- 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 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 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', '<leader><Enter>', 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.

Below are some examples:

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', '<A-g>', function()
    gitui:toggle()
end)

Screenshot

gitui

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', '<A-b>', function()
    btop:toggle()
end)

Screenshot

btop

πŸ’ Credits

More Repositories

1

Comment.nvim

🧠 πŸ’ͺ // Smart and powerful comment plugin for neovim. Supports treesitter, dot repeat, left-right/up-down motions, hooks, and more
Lua
2,434
star
2

Navigator.nvim

✨ Smoothly navigate between neovim and terminal multiplexer(s) ✨
Lua
301
star
3

dotfiles

🏑 /.dotfiles | Includes configs for neovim, tmux, zsh, alacrity, kitty, and more | Managed by GNU stow
Lua
274
star
4

lemmy-help

Every one needs help, so lemmy-help you! A CLI to generate vim/nvim help doc from emmylua
Rust
127
star
5

snm

🀏 Smol and simple node version manager written in rust πŸ¦€
Rust
98
star
6

BufOnly.nvim

Lua/Neovim port of BufOnly.vim with some changes
Lua
31
star
7

zenv

Dotenv (.env) loader written in rust πŸ¦€
Rust
28
star
8

Surround.nvim

[Alpha] Incoming successor to vim-surround
Lua
23
star
9

Sakura.nvim

Nice color scheme for neovim
Lua
21
star
10

prettierrc.nvim

Apply editor settings from prettier config
Lua
19
star
11

site

Personal portfolio and blog
JavaScript
18
star
12

random.ly

Real Time Chat App built with React, Redux, React Router, Node.js, Express, MongoDB and Socket.io
JavaScript
6
star
13

ky

πŸ”‘ ky - Simple and secure password manager
Rust
2
star
14

traefik-ecs-fargate

HCL
2
star
15

Buffers.nvim

Some useful functions to deal with buffers
Lua
1
star
16

react-image-uploader

Demo:
JavaScript
1
star
17

ender3v3ke_klipper

Klipper backup config for Ender 3 v3 KE
Python
1
star
18

dark-black-portfolio

Dark & Flat Design Portfolio
CSS
1
star
19

crafting-interpreters

Rust
1
star
20

dockerfiles

A collection of dockerfiles for different projects πŸ˜–
Dockerfile
1
star
21

listrrr

Issue and Project tracker build w/ GraphQl, Apollo & React πŸ”₯. Wrapped with πŸ‹ Docker.
TypeScript
1
star
22

nodegen

A CLI tool for creating nodejs app πŸš€
JavaScript
1
star
23

gruvbox-material

Fork of gruvbox-material
Vim Script
1
star
24

gotodo

A small todo backend built with golang, sqlite
Go
1
star