Skip to content

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

License

Notifications You must be signed in to change notification settings

jonatan-branting/FTerm.nvim

This branch is 16 commits behind numToStr/FTerm.nvim:master.

Folders and files

NameName
Last commit message
Last commit date

Latest commit

0911ab9 Β· Nov 13, 2021

History

49 Commits
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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
local map = vim.api.nvim_set_keymap
local opts = { noremap = true, silent = true }

map('n', '<A-i>', '<CMD>lua require("FTerm").toggle()<CR>', opts)
map('t', '<A-i>', '<C-\\><C-n><CMD>lua require("FTerm").toggle()<CR>', opts)

Configuration

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

{
    -- Filetype of the terminal buffer
    ft = 'FTerm',

    -- Command to run inside the terminal. It could be a `string` or `table`
    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.
    auto_close = true,

    -- Highlight group for the terminal. See `:h winhl`
    hl = 'Normal',

    -- Transparency of the floating window. See `:h winblend`
    blend = 0,

    -- Object containing the terminal window dimensions.
    -- The value for each field should be between `0` and `1`
    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
    }

    -- Callback invoked when the terminal exits.
    -- See `:h jobstart-options`
    on_exit = nil,

    -- Callback invoked when the terminal emits stdout data.
    -- See `:h jobstart-options`
    on_stdout = nil,

    -- Callback invoked when the terminal emits stderr data.
    -- See `:h jobstart-options`
    on_stderr = nil,
}

πŸ”₯ Usage

  • Opening the terminal
lua require('FTerm').open()

-- or create a vim command
vim.cmd('command! FTermOpen lua require("FTerm").open()')
  • 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.cmd('command! FTermClose lua require("FTerm").close()')
  • Exiting the terminal

Unlike closing, this will remove the terminal session

lua require('FTerm').exit()

-- or create a vim command
vim.cmd('command! FTermExit lua require("FTerm").exit()')
  • Toggling the terminal
lua require('FTerm').toggle()

-- or create a vim command
vim.cmd('command! FTermClose lua require("FTerm").toggle()')
  • 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.

NOTE: There is no need to add \n at the end of the command

-- run() can take `string` or `table` just like `cmd` config
lua require('FTerm').run('man ls') -- with string
lua require('FTerm').run({'yarn', 'build'})
lua require('FTerm').run({'node', vim.api.nvim_get_current_buf()})

-- Or you can do this
vim.cmd('command! ManLs lua require("FTerm").run("man ls")')
vim.cmd('command! YarnBuild lua require("FTerm").run({"yarn", "build"})')

⚑ 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.

lua require('FTerm').scratch({ cmd = 'yarn build' })
lua require('FTerm').scratch({ cmd = {'cargo', 'build', '--target', os.getenv('RUST_TARGET')} })

-- Scratch terminals are awesome because you can do this
vim.cmd('command! YarnBuild lua require("FTerm").scratch({ cmd = "yarn build" })')
vim.cmd('command! CargoBuild lua require("FTerm").scratch({ cmd = {"cargo", "build", "--target", os.getenv("RUST_TARGET")} })')

✨ 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
function _G.__fterm_gitui()
    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
function _G.__fterm_btop()
    btop:toggle()
end

Screenshot

btop

πŸ’ Credits

About

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

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Lua 100.0%