Skip to content

Commit 533ec4f

Browse files
ryanmsnyderryanmsnyder
committed
docs: update README
1 parent 40181f8 commit 533ec4f

3 files changed

Lines changed: 104 additions & 33 deletions

File tree

‎README.md‎

Lines changed: 94 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,21 @@
1-
<p align="center">
2-
A Telescope extension to manage toggleterm's terminal buffers
3-
</p>
1+
<h1 align="center">
2+
A Telescope extension to manage Toggleterm's terminals in NeoVim
3+
</h1>
44

55
## ✨ Features
66

7-
- List and switch between all terminal buffers opened with `toggleterm.nvim`
7+
- List all terminal buffers
8+
- Create, delete, toggle, and rename terminal buffers within the Telescope window
89
- Easily customize the appearance of the Telescope window
9-
- Map pre-defined and custom actions to keybindings
1010

11-
## ⚡ Requirements
11+
## 🛠️ Requirements
1212

13-
- [`telescope`](https://github.com/nvim-telescope/telescope.nvim) plugin.
14-
- [`nvim-toggleterm`](https://github.com/akinsho/nvim-toggleterm.lua) plugin.
13+
- [`telescope`](https://github.com/nvim-telescope/telescope.nvim) plugin
14+
- [`toggleterm`](https://github.com/akinsho/nvim-toggleterm.lua) plugin
1515

16-
## 🛠️ Quickstart
16+
## ⚡ Quickstart
1717

18-
Install using [ `lazy.nvim` ](https://github.com/folke/lazy.nvim) in lua:
18+
### Lazy
1919

2020
```lua
2121
{
@@ -46,25 +46,32 @@ By default, the below table is passed to the `setup` function:
4646

4747
```lua
4848
{
49-
mappings = {}, -- key mappings bound inside the telescope window
49+
mappings = {
50+
i = {
51+
["<CR>"] = { action = actions.toggle_term, exit_on_action = false }, -- toggles terminal open/closed
52+
["<C-i>"] = { action = actions.create_term, exit_on_action = false }, -- creates a new terminal buffer
53+
["<C-d>"] = { action = actions.delete_term, exit_on_action = false }, -- deletes a terminal buffer
54+
["<C-r>"] = { action = actions.rename_term, exit_on_action = false }, -- provides a prompt to rename a terminal
55+
},
56+
}, -- key mappings bound inside the telescope window
5057
telescope_titles = {
5158
preview = "Preview", -- title of the preview buffer in telescope
52-
prompt = "Pick Term", -- title of the prompt buffer in telescope
59+
prompt = "Terminals", -- title of the prompt buffer in telescope
5360
results = "Results", -- title of the results buffer in telescope
5461
},
5562
results = {
56-
fields = {
57-
"state",
58-
"space",
59-
"term_icon",
60-
"term_name",
63+
fields = { -- fields that will appear in the results of the telescope window
64+
"state", -- the state of the terminal buffer: h = hidden, a = active
65+
"space", -- adds space between fields, if desired
66+
"term_icon", -- a terminal icon
67+
"term_name", -- toggleterm's display_name if it exists, else the terminal's id assigned by toggleterm
6168
},
6269
separator = " ", -- the character that will be used to separate each field provided in results.fields
63-
term_icon = "", -- the icon that will be used for the term_icon in results.fields
70+
term_icon = "", -- the icon that will be used for term_icon in results.fields
6471

6572
},
6673
search = {
67-
field = "term_name" -- the field that telescope fuzzy search will use
74+
field = "term_name" -- the field that telescope fuzzy search will use when typing in the prompt
6875
},
6976
sort = {
7077
field = "term_name", -- the field that will be used for sorting in the telesocpe results
@@ -73,9 +80,10 @@ By default, the below table is passed to the `setup` function:
7380
}
7481
```
7582

83+
7684
| Property | Type | Default Value | Description |
7785
|--------------------|--------------------------------|---------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
78-
| **mappings** | `table` | | A table of key mappings for different modes. Each mode (like 'i' for insert mode, 'n' for normal mode) is a key in the table and maps to another table, where the key is the key combination (e.g., "<CR>") and the value is a table with the fields 'action' and 'exit_on_action'. The 'action' field is a function that will be called when the key combination is pressed, and 'exit_on_action' is a boolean that determines whether telescope should be exited after the action is performed. See Mappings for more info. |
86+
| **mappings** | `table` | | A table of key mappings for different modes. Each mode (`i` for insert mode, `n` for normal mode) is a key in the table and maps to another table, where the key is the key combination (e.g., "<C-r>") and the value is a table with the fields `action` and `exit_on_action`. The `action` field is a function that will be called when the key combination is pressed, and `exit_on_action` is a boolean that determines whether telescope should be exited after the action is performed. See [Mappings](https://github.com/ryanmsnyder/toggleterm-manager.nvim/blob/readme/README.md#mappings) for more info. |
7987
| **telescope_titles.preview** | `string` | "Preview" | Title of the preview buffer in telescope. Any string. |
8088
| **telescope_titles.prompt** | `string` | " Pick Term" | Title of the prompt buffer in telescope. Any string. |
8189
| **telescope_titles.results** | `string` | "Results" | Title of the results buffer in telescope. Any string. |
@@ -111,17 +119,71 @@ Note that each key in the table should correspond to the NeoVim mode that the ma
111119

112120
#### Actions
113121

114-
There are six pre-built actions that can be mapped to key bindings within the telescope window.
122+
There are six pre-defined actions that can be mapped to key bindings within the telescope window.
123+
124+
> **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.
125+
126+
The below table displays the behavior of each action in `actions/init.lua` given different values for `exit_on_action` and `toggleterm`'s' `direction` property that's passed to its [`setup`](https://github.com/akinsho/toggleterm.nvim#setup) function.
127+
128+
<table>
129+
<tr>
130+
<th>Action</th>
131+
<th colspan="2"><code>exit_on_action = true</code></th>
132+
<th colspan="2"><code>exit_on_action = false</code></th>
133+
</tr>
134+
<tr>
135+
<th></th>
136+
<th><code>direction = float</code></th>
137+
<th><code>direction != float</code></th>
138+
<th><code>direction = float</code></th>
139+
<th><code>direction != float</code></th>
140+
</tr>
141+
<tr>
142+
<td><code>create_term</code></td>
143+
<td>Create and focus a new terminal</td>
144+
<td>Create and focus a new terminal</td>
145+
<td>Create a <i>hidden</i> terminal</td>
146+
<td>Create a new terminal</td>
147+
</tr>
148+
<tr>
149+
<td><code>create_and_name_term</code></td>
150+
<td>Create, name, and focus a new terminal</td>
151+
<td>Create, name, and focus a new terminal</td>
152+
<td>Create a <i>hidden</i> terminal and name it</td>
153+
<td>Create and name a new terminal</td>
154+
</tr>
155+
<tr>
156+
<td><code>rename_term</code></td>
157+
<td>Rename and focus the terminal if open</td>
158+
<td>Rename and focus the terminal if open</td>
159+
<td>Rename the terminal</td>
160+
<td>Rename the terminal</td>
161+
</tr>
162+
<tr>
163+
<td><code>open_term</code></td>
164+
<td>Open and focus the terminal</td>
165+
<td>Open and focus the terminal</td>
166+
<td>Nothing will happen</td>
167+
<td>Open the terminal</td>
168+
</tr>
169+
<tr>
170+
<td><code>toggle_term</code></td>
171+
<td>Toggle terminal open or closed, focus if open</td>
172+
<td>Toggle terminal open or closed, focus if open</td>
173+
<td>Toggle terminal open or closed</td>
174+
<td>Toggle terminal open or closed</td>
175+
</tr>
176+
<tr>
177+
<td><code>delete_term</code></td>
178+
<td>Delete the terminal</td>
179+
<td>Delete the terminal</td>
180+
<td>Delete the terminal</td>
181+
<td>Delete the terminal</td>
182+
</tr>
183+
</table>
184+
115185

116-
- `create_term`: Create a new terminal and open it. If `exit_on_action = true`, focus it. If `toggleterm`'s direction is `float` and `exit_on_action = false`, create a hidden terminal.
117-
- `create_and_name_term`: Create and name a new terminal and open it. If `exit_on_action = true`, focus it. If `toggleterm`'s direction is `float` and `exit_on_action = false`, create a hidden terminal. The name will be reflected in the `term_name` field if it's provided in `results.field`.
118-
- `rename_term`: Rename a terminal. If `exit_on_action = true` and the terminal is open, focus it. The name will be reflected in the `term_name` field if it's provided in `results.field`.
119-
- `open_term`: Open a terminal. If `exit_on_action = true`, focus it. If `exit_on_action = false` and `toggleterm`'s direction is `float`, this action won't do anything.
120-
- `toggle_term`: Toggle a terminal open or closed. If toggling open and `exit_on_action = true`, focus it.
121-
- `delete_term`: Delete a terminal.
122186

123-
> [!Floating toggleterm windows]
124-
> 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` is `float`. This is because of how NeoVim handles floating windows. Telescope is already a floating window so if, for example, `direction` is set to `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.
125187

126188
#### Custom Actions
127189

@@ -156,6 +218,8 @@ The background and foreground colors of the results fields can also be customize
156218

157219
#### Examples
158220

221+
Example of only providing fields (no highlight groups). When a highlight group is not specified for a field, `toggleterm-manager` chooses the highlight group:
222+
159223
```lua
160224
local toggleterm_manager = require("toggleterm-manager")
161225
local actions = toggleterm_manager.actions
@@ -167,7 +231,7 @@ toggleterm_manager.setup {
167231
}
168232
```
169233

170-
Example of providing highlight groups:
234+
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.
171235

172236
```lua
173237
results = {

‎lua/config.lua‎

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,18 @@
1+
local actions = require("lib.actions")
12
local M = {}
23

34
local defaults = {
4-
mappings = {}, -- key mappings bound inside the telescope window
5+
mappings = {
6+
i = {
7+
["<CR>"] = { action = actions.toggle_term, exit_on_action = false },
8+
["<C-i>"] = { action = actions.create_term, exit_on_action = false },
9+
["<C-d>"] = { action = actions.delete_term, exit_on_action = false },
10+
["<C-r>"] = { action = actions.rename_term, exit_on_action = false },
11+
},
12+
}, -- key mappings bound inside the telescope window
513
telescope_titles = {
614
preview = "Preview", -- title of the preview buffer in telescope
7-
prompt = "Pick Term", -- title of the prompt buffer in telescope
15+
prompt = "Terminals", -- title of the prompt buffer in telescope
816
results = "Results", -- title of the results buffer in telescope
917
},
1018
results = {

‎nohup.out‎

Lines changed: 0 additions & 1 deletion
This file was deleted.

0 commit comments

Comments
 (0)