buffers.nvim

KO | EN

gitlite — search

#python #hacktoberfest #typescript #go #machine-learning #docker #macos #nodejs #java #windows #cli #vue #awesome-list #mcp

(★ 18)

simple buffer switcher for neovim

buffers.nvim Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# About
Simple and efficient buffer switcher, using minimum of 2 keystrokes to get anywhere.
Whole plugin is just a single window and command.
This plugin is to meet my personal requirements, ~~which doesn't include colors or icons~~, although I might still add more features.

# Screenshot
![screenshot](https://github.com/user-attachments/assets/490ddd96-fb05-43bf-aa98-8fd66e819941)

# Installation
Just use any package manager to install.
`setup()` function is **not** provided, instead see [configuration](#configuration).
`icon` option depends on [nvim-web-devicons](https://github.com/nvim-tree/nvim-web-devicons), which must be loaded beforehand.

# Usage
Single command, `:BuffersToggle`, toggles buffer window.
Every buffer is filtered using customizable predicate,
by default that is: buffer exists and has `buflisted` option set (*see [defaults](#defaults)*)
In that window, only survived buffers are displayed.

From this window, any buffer can be opened using provided key next to it and buffers window is closed.

I recommend mapping `:BuffersToggle` to single key for fastest navigation.

# Configuration
Whole configuration is done via `vim.g.buffers_config` table which is checked every time buffers window opens,
so it can be tweaked, without reloading.
## Defaults
```lua
---@type buffers.Config
{
	width = 70, -- window width (longer lines are not yet handled)
	min_heigh = 6, -- minimum window height
	position = 'bottom_right', -- window position (can be 'bottom_right', 'top_right' or 'center')
	border = vim.o.winborder, -- window border (accepts same values as vim.api.keyset.win_config.border)
	win_opts = {}, -- additional window local options
	separator = ' | ', -- separator between char and buffer name
	icon = false, -- whether to show icons or not (requires nvim-tree/nvim-web-devicons)
	-- characters that can be bound to buffers
	chars = "qwertyuiopasdfghjklzxcvbnm1234567890",
	-- if non of the characters from `chars` is available use this list (see #internals for more info)
	backup_chars = "QWERTYUIOPASDFGHJKLZXCVBNM_-",
	-- called for every buffer, to determine if it should be listed in buffers window
	filter = function(bufnr)
		return vim.fn.buflised(bufnr)
	end,
	-- how to format buffer names ('relative_path', 'filename_first' or custom function)
	-- for function usage see #formatters
	formatter = 'relative_path',
	-- which keys are used to close the buffers window, without warning
	-- note: <C-c> always closes the window
	close_keys = {"<Esc>"},
}
```

# Internals
## Picking chars
Single character bound to each buffer is generated by simple algorithm called `get_buffer_char`.
```lua
local function get_buffer_char(name, buffer_table, chars)
	local char = name:sub(1, 1)
	local i = 2
	while buffer_table:get(char) or chars:find(char, 1, true) == nil do
		if i > #name then
			return nil
		end
		char = name:sub(i, i)
		i = i + 1
	end
	return char
end
```
This function returns first valid character from buffer's name.
Character is valid if it's:
- not already used
- found in `chars` string

Usage of this function is more interesting:
- For each buffer, first it's called with `chars` string from configuration.
- If `nil` is returned, than it's called with `backup_chars`.
- If that also fails, first available character from `chars` and `backup_chars` is used.

Accidental overlap of keys is pretty much impossible.

## Mapping chars
For actually mapping character to buffers, `getcharstr` function is used.
Before commit `a541273`, I was using keymaps which where problematic!
[thanks to this comment](https://www.reddit.com/r/neovim/comments/1lhuqgp/comment/mzaa6u5/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button)

`close_keys` option was added because of `getcharstr`,
so `BuffersToggle` command is less useful, and can just be `BuffersOpen`, but it still functions as toggle.

## Formatters
each formatter is a function that takes full path to a file and returns two values:
1. `string` formatted string to be used
2. `integer[]` pair which denotes range for highlighting with `Comment` hl group.
This should be used for less important info, like file path to make file name stand out more.
Range is end-exclusive.

# TODO
- [x] add custom formatting option
- [x] add icons
- [ ] add more highlights
- [ ] add docs

# Contribution
PRs and Issues are welcome!

buffers.nvim

buffers.nvim Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

buffers.nvim

buffers.nvim Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README