A Telescope extension to manage Toggleterm's terminals in NeoVim

https://github.com/ryanmsnyder/toggleterm-manager.nvim/assets/41448219/0aa59e55-e421-47ee-8654-81539f4197b4

✨ Features

• List all Toggleterm terminal buffers and preview them in Telescope
• Create, open, delete, toggle, and rename terminal buffers
• Easily customize the appearance of the Telescope window

🛠️ Requirements

• Telescope
• Toggleterm

⚡ Quickstart

Lazy

{
  "ryanmsnyder/toggleterm-manager.nvim",
  dependencies = {
    "akinsho/nvim-toggleterm.lua",
    "nvim-telescope/telescope.nvim",
    "nvim-lua/plenary.nvim", -- only needed because it's a dependency of telescope
  },
  config = true,
}

Open toggleterm-manager by either:

• running the command :Telescope toggleterm_manager
• calling lua require('toggleterm-manager').open()

Keep reading if you want to change the default configuration.

⚙️ Configuration (optional)

If you want to change the defaults, instead of passing true to lazy's config option, either:

Pass the desired options to lazy's opts:

opts = {
  titles = {
    prompt = "Pick Term",
    results = "Terminals"
  },
  -- more overrides if desired
},

or call toggletem-manager's setup function with the options you want to change:

config = function()
  require("toggleterm-manager").setup {
    titles = {
      prompt = "Pick Term",
      results = "Terminals"
    },
    -- more overrides if desired
  }
end

Defaults

By default, the below table is passed to the setup function:

{
  mappings = { -- key mappings bound inside the telescope window
    i = {
      ["<CR>"] = { action = actions.toggle_term, exit_on_action = false }, -- toggles terminal open/closed
      ["<C-i>"] = { action = actions.create_term, exit_on_action = false }, -- creates a new terminal buffer
      ["<C-d>"] = { action = actions.delete_term, exit_on_action = false }, -- deletes a terminal buffer
      ["<C-r>"] = { action = actions.rename_term, exit_on_action = false }, -- provides a prompt to rename a terminal
    },
  },
  titles = {
    preview = "Preview", -- title of the preview buffer in telescope
    prompt = " Terminals", -- title of the prompt buffer in telescope
    results = "Results", -- title of the results buffer in telescope
  },
  results = {
    fields = { -- fields that will appear in the results of the telescope window
      "state", -- the state of the terminal buffer: h = hidden, a = active
      "space", -- adds space between fields, if desired
      "term_icon", -- a terminal icon
      "term_name", -- toggleterm's display_name if it exists, else the terminal's id assigned by toggleterm
    },
    separator = " ", -- the character that will be used to separate each field provided in results.fields  
    term_icon = "", -- the icon that will be used for term_icon in results.fields
  },
  search = {
    field = "term_name" -- the field that telescope fuzzy search will use when typing in the prompt
  },
  sort = {
    field = "term_name", -- the field that will be used for sorting in the telesocpe results
    ascending = true, -- whether or not the field provided above will be sorted in ascending or descending order
  },
}

Configuration Specs

Mappings

If you'd like to override the default keybindings, the mappings table should look something like this:

local toggleterm_manager = require("toggleterm-manager")
local actions = toggleterm_manager.actions

toggleterm_manager.setup {
    mappings = {
        i = {
          ["<CR>"] = { action = actions.create_and_name_term, exit_on_action = true },
          ["<C-d>"] = { action = actions.delete_term, exit_on_action = false },
        },
        n = {
          ["<CR>"] = { action = actions.create_and_name_term, exit_on_action = true },
          ["x"] = { action = actions.delete_term, exit_on_action = false },
        },
    },
}

Note that each key in the table should correspond to the NeoVim mode that the mappings should apply to (i for insert, n for normal). Each mode key should contain another table of key/value pairs where the key is the keybinding and the value is another table of key/value pairs. The valid keys of that table are action, which takes a function that manipulates a terminal in some way and exit_on_action, which determines if the Telescope window should be closed on the execution of the action.

Actions

There are six pre-defined actions that can be mapped to key bindings within the Telescope window.

Floating Toggleterm windows: When configuring Toggleterm (not toggleterm-manager), there is a property called direction, which takes a value of horizontal, vertical, or float. Some of the actions behave differently if direction = float. This is because of how NeoVim handles floating windows. Telescope is already a floating window so if, for example, direction = float, and the create_term action is called with exit_on_action = false, there would normally be a flash caused by opening a Toggleterm float and switching back to Telescope really fast. To prevent this, the Toggleterm window will be created as a hidden terminal. Note that the open_mapping in Toggleterm config won't be able to toggle these terminals open/closed.

The below table displays the behavior of each action given different values for exit_on_action and Toggleterm's direction property that's passed to its setup function.

Custom Actions

User-created functions can also be provided. Any function passed in as an action will receive two arguments: prompt_bufnr and exit_on_action.

local function my_custom_action(prompt_bufnr, exit_on_action)

    -- get current telescope selection
    local selection = actions_state.get_selected_entry()
    if selection == nil then
        return
    end

    -- get toggleterm's Terminal object
    local term = selection.value

    -- do something with the terminal
    term:open()
end

• Once Toggleterm's Terminal object is retrieved as seen above, any of Toggleterm's Terminal methods can be used (term:focus(), term:spawn(), etc).

• Note that this is a simplified exampled. Getting actions to work as intended can feel a bit hacky because of both Toggleterm and Telescope controlling which NeoVim window should be focused.

• See actions/init.lua for examples of creating actions.

Results

The results property allows for easy customization of how Toggleterm's terminal buffers appear in the Telescope results buffer. results.fields allows for specifying the order that the results fields should appear, from left to right. Any combination and any number of the valid fields may be provided.

Valid Strings for results.fields

Results Highlight Groups

The background and foreground colors of the results fields can also be customized by pairing any one of the above fields with a valid highlight group.

Examples

Example of only providing fields (no highlight groups). When a highlight group is not specified for a field, toggleterm-manager chooses the highlight group:

local toggleterm_manager = require("toggleterm-manager")
local actions = toggleterm_manager.actions

toggleterm_manager.setup {
  results = {
    fields = { "term_icon", "term_name", "space", "state" }
  },
}

Example of providing highlight groups for some fields and not for others. When a highlight group is paired with a field in a table, that highlight group overrides the default that toggleterm-manager chooses.

results = {
  fields = { "state", "space", { "bufnr", "TelescopeResultsIdentifier" }, "space", "term_icon", { "bufname", "Function" } }
}