# cybu.nvim
**Repository Path**: mirrors_ghillb/cybu.nvim
## Basic Information
- **Project Name**: cybu.nvim
- **Description**: Neovim plugin that offers context when cycling buffers in the form of a customizable notification window.
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 1
- **Forks**: 0
- **Created**: 2023-02-27
- **Last Updated**: 2026-01-26
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Cybu.nvim
**_Cy_**[cle]**_bu_**[ffer]**_.nvim_** provides two modes. The first is essentially a wrapper around `:bnext` & `:bprevious`, which adds a customizable notification window, that shows the buffer in focus and its neighbors, to provide context when cycling the buffer list with the provided plugin commands / key bindings.
The second mode adds the same customizable window providing context, but the list of buffers is ordered by last used. It is more akin to the `[Ctrl] + [Tab]` functionality a web browser might provide.
See [:help cybu.nvim](https://github.com/ghillb/cybu.nvim/blob/main/doc/cybu.nvim.txt) for the docs.
More previews
## Requirements
- Neovim >= 0.7.0
## Installation
### Quickstart with [lazy.nvim](https://github.com/folke/lazy.nvim)
```lua
{
"ghillb/cybu.nvim",
branch = "main", -- timely updates
-- branch = "v1.x", -- won't receive breaking changes
dependencies = { "nvim-tree/nvim-web-devicons", "nvim-lua/plenary.nvim" }, -- optional for icon support
keys = {
{ "K", "(CybuPrev)", mode = "n", desc = "Cybu Prev" },
{ "J", "(CybuNext)", mode = "n", desc = "Cybu Next" },
{ "", "(CybuLastusedPrev)", mode = { "n", "v" }, desc = "Cybu Last Used Prev" },
{ "", "(CybuLastusedNext)", mode = { "n", "v" }, desc = "Cybu Last Used Next" },
},
opts = {}, -- automatically calls require("cybu").setup()
}
```
After installing, cycle buffers and display the context window by using the exemplary key bindings defined above.
### Setup with other plugin managers
If you use another plugin manager, install `"ghillb/cybu.nvim"` and optionally `"nvim-tree/nvim-web-devicons"` with it, like you would with any other plugin.
Setup up **_Cybu_** by calling its setup function and placing the respective key bindings, somewhere into your `init.lua`.
```lua
require("cybu").setup()
vim.keymap.set("n", "[b", "(CybuPrev)")
vim.keymap.set("n", "]b", "(CybuNext)")
vim.keymap.set("n", "", "(CybuLastusedPrev)")
vim.keymap.set("n", "", "(CybuLastusedNext)")
```
Hint: If you use the `` key, map `vim.keymap.set( "n", "", "")` to keep it separate from `` (See: [neovim/pull/17932](https://github.com/neovim/neovim/pull/17932#issue-1188088238)).
## Configuration
If you want to customize the appearance and behaviour of **_Cybu_**, you can do it by adapting the configuration table.
```lua
require("cybu").setup({
position = {
relative_to = "win", -- win, editor, cursor
anchor = "topcenter", -- topleft, topcenter, topright,
-- centerleft, center, centerright,
-- bottomleft, bottomcenter, bottomright
vertical_offset = 10, -- vertical offset from anchor in lines
horizontal_offset = 0, -- vertical offset from anchor in columns
max_win_height = 5, -- height of cybu window in lines
max_win_width = 0.5, -- integer for absolute in columns
-- float for relative to win/editor width
},
style = {
path = "relative", -- absolute, relative, tail (filename only),
-- tail_dir (filename & parent dir)
path_abbreviation = "none", -- none, shortened
border = "rounded", -- single, double, rounded, none
separator = " ", -- string used as separator
prefix = "…", -- string used as prefix for truncated paths
padding = 1, -- left & right padding in number of spaces
hide_buffer_id = true, -- hide buffer IDs in window
devicons = {
enabled = true, -- enable or disable web dev icons
colored = true, -- enable color for web dev icons
truncate = true, -- truncate wide icons to one char width
},
highlights = { -- see highlights via :highlight
current_buffer = "CybuFocus", -- current / selected buffer
adjacent_buffers = "CybuAdjacent", -- buffers not in focus
background = "CybuBackground", -- window background
border = "CybuBorder", -- border of the window
},
},
behavior = { -- set behavior for different modes
mode = {
default = {
switch = "immediate", -- immediate, on_close
view = "rolling", -- paging, rolling
},
last_used = {
switch = "on_close", -- immediate, on_close
view = "paging", -- paging, rolling
update_on = "buf_enter", -- buf_enter, cursor_moved
},
auto = {
view = "rolling", -- paging, rolling
},
},
show_on_autocmd = false, -- event to trigger cybu (eg. "BufEnter")
},
display_time = 750, -- time the cybu window is displayed
exclude = { -- filetypes, cybu will not be active
"neo-tree",
"fugitive",
"qf",
},
filter = {
unlisted = true, -- filter & fallback for unlisted buffers
},
fallback = function() end, -- arbitrary fallback function
-- used in excluded filetypes
})
```
## Features
- Two modes: cycle `:buffers` list or cycle last used buffers
- **Cursor-based MRU ordering**: Control when buffers are marked as "used"
- Adaptive size of the **_Cybu_** window
- Various styling & positioning options
- Exclude filetypes and define fallback
- Autocmd events `CybuOpen` & `CybuClose`
- Trigger context window on arbitrary autocommand events
### Advanced: Cursor Movement Based MRU
The `update_on` option in `last_used` mode controls when buffers are moved to the most recently used position:
- `"buf_enter"` (default): Updates MRU order on every buffer switch
- `"cursor_moved"`: Only updates MRU when cursor moves in the buffer
- `"text_changed"`: Only updates MRU when text is actually edited
```lua
require("cybu").setup({
behavior = {
mode = {
last_used = {
update_on = "text_changed",
}
}
}
})
```
### Experimental: Custom Buffer Providers
**⚠️ Experimental Feature**: This feature is experimental and the API may change in future versions. Use with caution in production environments.
You can integrate cybu with other buffer management plugins like [grapple.nvim](https://github.com/cbochs/grapple.nvim) or [harpoon.nvim](https://github.com/ThePrimeagen/harpoon) by providing a custom buffer provider function:
```lua
require("cybu").setup({
experimental = {
buffer_provider = function()
-- Return table of buffer objects: {{bufnr=1, filename="file.lua"}, ...}
-- Logic to fetch buffers from your preferred source
return custom_buffer_list
end
}
})
```
See `examples/buffer_providers.lua` for working examples with grapple.nvim, harpoon.nvim, and advanced usage patterns.
## Breaking changes
If breaking changes (will be kept to a minimum) are of no concern to you, use the `main` branch. Otherwise you can use the version pinned branches, e.g. `v1.x`. These branches will only receive bug fixes and other non-breaking changes.
## Roadmap
- Add possibility to further customize the entry layout
- Offer additional modes to cycle buffers
## Testing via [plenary.nvim](https://github.com/nvim-lua/plenary.nvim)
Run tests with
```bash
make tests
```