.
akinsho-bufferline.nvim-655133c/README.md 0000664 0000000 0000000 00000030541 14741505237 0020002 0 ustar 00root root 0000000 0000000 [](https://github.com/akinsho/bufferline.nvim/actions/workflows/ci.yaml)
bufferline.nvim
A snazzy 💅 buffer line (with tabpage integration) for Neovim built using lua.
- [Requirements](#requirements)
- [Installation](#installation)
- [Usage](#usage)
- [Configuration](#configuration)
- [Features](#features)
- [Alternate styling](#alternate-styling)
- [Hover events](#hover-events)
- [Underline indicator](#underline-indicator)
- [Tabpages](#tabpages)
- [LSP indicators](#lsp-indicators)
- [Groups](#groups)
- [Sidebar offsets](#sidebar-offsets)
- [Numbers](#numbers)
- [Picking](#picking)
- [Pinning](#pinning)
- [Unique names](#unique-names)
- [Close icons](#close-icons)
- [Re-ordering](#re-ordering)
- [Custom areas](#custom-areas)
- [How do I see only buffers per tab?](#how-do-i-see-only-buffers-per-tab)
- [Caveats](#caveats)
- [FAQ](#faq)
This plugin shamelessly attempts to emulate the aesthetics of GUI text editors/Doom Emacs.
It was inspired by a screenshot of DOOM Emacs using [centaur tabs](https://github.com/ema2159/centaur-tabs).
## Requirements
- Neovim 0.8+
- A patched font (see [nerd fonts](https://github.com/ryanoasis/nerd-fonts))
- A colorscheme (either your custom highlight or a maintained one somewhere)
## Installation
It is advised that you specify either the latest tag or a specific tag and bump them manually if you'd prefer to inspect changes before updating.
If you'd like to use an older version of the plugin compatible with nvim-0.6.1 and below please change your tag to `tag = "v1.*"`
**Lua**
```lua
-- using packer.nvim
use {'akinsho/bufferline.nvim', tag = "*", requires = 'nvim-tree/nvim-web-devicons'}
-- using lazy.nvim
{'akinsho/bufferline.nvim', version = "*", dependencies = 'nvim-tree/nvim-web-devicons'}
```
**Vimscript**
```vim
Plug 'nvim-tree/nvim-web-devicons' " Recommended (for coloured icons)
" Plug 'ryanoasis/vim-devicons' Icons without colours
Plug 'akinsho/bufferline.nvim', { 'tag': '*' }
```
## Usage
See the docs for details `:h bufferline.nvim`
You need to be using `termguicolors` for this plugin to work, as it reads the hex `gui` color values
of various highlight groups.
**Vimscript**
```vim
" In your init.lua or init.vim
set termguicolors
lua << EOF
require("bufferline").setup{}
EOF
```
**Lua**
```lua
vim.opt.termguicolors = true
require("bufferline").setup{}
```
You can close buffers by clicking the close icon or by _right clicking_ the tab anywhere
## Configuration
for more details on how to configure this plugin in details please see `:h bufferline-configuration`
## Features
- Colours derived from colorscheme where possible.
- Sort buffers by `extension`, `directory` or pass in a custom compare function
- Configuration via lua functions for greater customization.
#### Alternate styling
##### Slanted tabs
**NOTE**: some terminals require special characters to be padded so set the style to `padded_slant` if the appearance isn't right in your terminal emulator. Please keep in mind
though that results may vary depending on your terminal emulator of choice and this style might not work for all terminals
##### Sloped tabs
see: `:h bufferline-styling`
---
#### Hover events
**NOTE**: this is _only_ available for >= neovim 0.8+
see `:help bufferline-hover-events` for more information on configuration
---
#### Underline indicator
**NOTE**: as with the above your mileage will vary based on your terminal emulator. The screenshot above was achieved using kitty nightly (as of August 2022), with increased
underline thickness and an increased underline position so it sits further from the text
---
#### Tabpages
This plugin can also be set to show only tabpages. This can be done by setting the `mode` option to `tabs`. This will change the bufferline to a tabline
it has a lot of the same features/styling but not all.
A few things to note are
- Sorting doesn't work yet as that needs to be thought through.
- Grouping doesn't work yet as that also needs to be thought through.
---
#### LSP indicators
By setting `diagnostics = "nvim_lsp" | "coc"` you will get an indicator in the bufferline for a given tab if it has any errors
This will allow you to tell at a glance if a particular buffer has errors.
In order to customise the appearance of the diagnostic count you can pass a custom function in your setup.
snippet
```lua
-- rest of config ...
--- count is an integer representing total count of errors
--- level is a string "error" | "warning"
--- diagnostics_dict is a dictionary from error level ("error", "warning" or "info")to number of errors for each level.
--- this should return a string
--- Don't get too fancy as this function will be executed a lot
diagnostics_indicator = function(count, level, diagnostics_dict, context)
local icon = level:match("error") and " " or " "
return " " .. icon .. count
end
```
snippet
```lua
diagnostics_indicator = function(count, level, diagnostics_dict, context)
local s = " "
for e, n in pairs(diagnostics_dict) do
local sym = e == "error" and " "
or (e == "warning" and " " or " ")
s = s .. n .. sym
end
return s
end
```
The highlighting for the file name if there is an error can be changed by replacing the highlights for see:
`:h bufferline-highlights`
LSP indicators can additionally be reported conditionally, based on buffer context. For instance, you could disable reporting LSP indicators for the current buffer and only have them appear for other buffers.
```lua
diagnostics_indicator = function(count, level, diagnostics_dict, context)
if context.buffer:current() then
return ''
end
return ''
end
```
The first bufferline shows `diagnostic.lua` as the currently opened `current` buffer. It has LSP reported errors, but they don't show up in the bufferline.
The second bufferline shows `500-nvim-bufferline.lua` as the currently opened `current` buffer. Because the 'faulty' `diagnostic.lua` buffer has now transitioned from `current` to `visible`, the LSP indicator does show up.
---
#### Groups
The buffers this plugin shows can be grouped based on a users configuration. Groups are a way of allowing a user to visualize related buffers in clusters
as well as operating on them together e.g. by clicking the group indicator all grouped buffers can be hidden. They are partially inspired by
google chrome's tabs as well as centaur tab's groups.
see `:help bufferline-groups` for more information on how to set these up
---
#### Sidebar offsets
---
#### Numbers
You can prefix buffer names with either the `ordinal` or `buffer id`, using the `numbers` option.
Currently this can be specified as either a string of `buffer_id` | `ordinal` or a function
see `:help bufferline-numbers` for more details
---
#### Unique names
---
#### Close icons
---
#### Re-ordering
This order can be persisted between sessions (enabled by default).
---
#### Picking
---
#### Pinning
---
#### Custom areas
see `:help bufferline-custom-areas`
## How do I see only buffers per tab?
This behaviour is _not native in neovim_ there is no internal concept of localised buffers to tabs as
that is not how tabs were designed to work. They were designed to show an arbitrary layout of windows per tab.
You can get this behaviour using [scope.nvim](https://github.com/tiagovla/scope.nvim) with this plugin. Although I believe a better
long-term solution for users who want this functionality is to ask for real native support
for this upstream.
## Caveats
- This won't appeal to everyone's tastes. This plugin is opinionated about how the tabline
looks, it's unlikely to please everyone.
- I want to prevent this becoming a pain to maintain so I'll be conservative about what I add.
- This plugin relies on some basic highlights being set by your colour scheme
i.e. `Normal`, `String`, `TabLineSel` (`WildMenu` as fallback), `Comment`.
It's unlikely to work with all colour schemes. You can either try manually overriding the colours or
manually creating these highlight groups before loading this plugin.
- If the contrast in your colour scheme isn't very high, think an all black colour scheme, some of the highlights of
this plugin won't really work as intended since it depends on darkening things.
## FAQ
- **Why isn't the bufferline appearing?**
The most common reason for this that has come up in various issues is it clashes with
another plugin. Please make sure that you do not have another bufferline plugin installed.
If you are using `airline` make sure you set `let g:airline#extensions#tabline#enabled = 0`.
If you are using `lightline` this also takes over the tabline by default and needs to be deactivated.
If you are on Windows and use the GUI version of nvim (nvim-qt.exe) then also ensure, that `GuiTabline`
is disabled. For this create a file called `ginit.vim` in your nvim config directory and put the line
`GuiTabline 0` in it. Otherwise the QT tabline will overlay any terminal tablines.
- **Doesn't this plugin go against the "vim way"?**
This is much better explained by [buftablines's author](https://github.com/ap/vim-buftabline#why-this-and-not-vim-tabs).
Please read this for a more comprehensive answer to this question. The short answer to this is
buffers represent files in nvim and tabs, a collection of windows (or just one). Vim natively allows visualising tabs i.e. collections
of window, but not just the files that are open. There are _endless_ debates on this topic, but allowing a user to see what files they
have open doesn't go against any clearly stated vim philosophy. It's a text editor and not a religion 🙏.
Obviously this won't appeal to everyone, which isn't really a feasible objective anyway.
akinsho-bufferline.nvim-655133c/doc/ 0000775 0000000 0000000 00000000000 14741505237 0017265 5 ustar 00root root 0000000 0000000 akinsho-bufferline.nvim-655133c/doc/bufferline.txt 0000664 0000000 0000000 00000140612 14741505237 0022153 0 ustar 00root root 0000000 0000000 *bufferline.nvim* For Neovim version 0.5+ Last change: 2021 August 20
A snazzy bufferline for neovim written in lua
Author: Akin Sowemimo
==============================================================================
CONTENTS *bufferline*
*bufferline-contents*
Introduction...........................: |bufferline-introduction|
Usage..................................: |bufferline-usage|
Configuration..........................: |bufferline-configuration|
Hover Events...........................: |bufferline-hover-events|
Styling................................: |bufferline-styling|
Style Presets..........................: |bufferline-style-presets|
Tabpages...............................: |bufferline-tabpages|
Numbers................................: |bufferline-numbers|
LSP Diagnostics........................: |bufferline-diagnostics|
Groups.................................: |bufferline-groups|
Sorting................................: |bufferline-sorting|
Filtering..............................: |bufferline-filtering|
Commands...............................: |bufferline-commands|
Custom functions.......................: |bufferline-functions|
Pick...................................: |bufferline-pick|
Mappings...............................: |bufferline-mappings|
Highlights.............................: |bufferline-highlights|
Mouse actions..........................: |bufferline-mouse-actions|
Custom areas...........................: |bufferline-custom-areas|
Working with Elements..................: |bufferline-working-with-elements|
Issues.................................: |bufferline-issues|
==============================================================================
INTRODUCTION *bufferline-introduction*
A _snazzy_ 💅 buffer line (tab integration) for Neovim built
using `lua`.
This plugin shamelessly attempts to emulate the aesthetics of GUI text
editors/Doom Emacs. It was inspired by a screenshot of DOOM Emacs using
centaur tabs (https://github.com/ema2159/centaur-tabs). I don't intend to copy
all of it's functionality though.
==============================================================================
USAGE *bufferline-usage*
You are *strongly* advised to use `termguicolors` for this plugin,
especially if you are using a colorscheme that uses gui colour values. However
this plugin also works with cterm terminal colours. When `termguicolors` is
enabled, it reads the hex `gui` colour values of various highlight groups.
Otherwise it expects the user to explicitly specify colour numbers (most modern
terminals allow 256 colour values). Please be aware that if you choose to use
this option it will be *your* responsibility to make the colours work to your
liking. Please do not open an issue if you are unable to do so, as you use
this option entirely at your discretion. >vim
set termguicolors
" In your init.vim or init.lua
lua require"bufferline".setup()
<
==============================================================================
CONFIGURATION *bufferline-configuration*
The available configuration are:
>lua
local bufferline = require('bufferline')
bufferline.setup {
options = {
mode = "buffers", -- set to "tabs" to only show tabpages instead
style_preset = bufferline.style_preset.default, -- or bufferline.style_preset.minimal,
themable = true | false, -- allows highlight groups to be overriden i.e. sets highlights as default
numbers = "none" | "ordinal" | "buffer_id" | "both" | function({ ordinal, id, lower, raise }): string,
close_command = "bdelete! %d", -- can be a string | function, | false see "Mouse actions"
right_mouse_command = "bdelete! %d", -- can be a string | function | false, see "Mouse actions"
left_mouse_command = "buffer %d", -- can be a string | function, | false see "Mouse actions"
middle_mouse_command = nil, -- can be a string | function, | false see "Mouse actions"
indicator = {
icon = '▎', -- this should be omitted if indicator style is not 'icon'
style = 'icon' | 'underline' | 'none',
},
buffer_close_icon = '',
modified_icon = '● ',
close_icon = ' ',
left_trunc_marker = ' ',
right_trunc_marker = ' ',
--- name_formatter can be used to change the buffer's label in the bufferline.
--- Please note some names can/will break the
--- bufferline so use this at your discretion knowing that it has
--- some limitations that will *NOT* be fixed.
name_formatter = function(buf) -- buf contains:
-- name | str | the basename of the active file
-- path | str | the full path of the active file
-- bufnr | int | the number of the active buffer
-- buffers (tabs only) | table(int) | the numbers of the buffers in the tab
-- tabnr (tabs only) | int | the "handle" of the tab, can be converted to its ordinal number using: `vim.api.nvim_tabpage_get_number(buf.tabnr)`
end,
max_name_length = 18,
max_prefix_length = 15, -- prefix used when a buffer is de-duplicated
truncate_names = true, -- whether or not tab names should be truncated
tab_size = 18,
diagnostics = false | "nvim_lsp" | "coc",
diagnostics_update_in_insert = false, -- only applies to coc
diagnostics_update_on_event = true, -- use nvim's diagnostic handler
-- The diagnostics indicator can be set to nil to keep the buffer name highlight but delete the highlighting
diagnostics_indicator = function(count, level, diagnostics_dict, context)
return "("..count..")"
end,
-- NOTE: this will be called a lot so don't do any heavy processing here
custom_filter = function(buf_number, buf_numbers)
-- filter out filetypes you don't want to see
if vim.bo[buf_number].filetype ~= "" then
return true
end
-- filter out by buffer name
if vim.fn.bufname(buf_number) ~= "" then
return true
end
-- filter out based on arbitrary rules
-- e.g. filter out vim wiki buffer from tabline in your work repo
if vim.fn.getcwd() == "" and vim.bo[buf_number].filetype ~= "wiki" then
return true
end
-- filter out by it's index number in list (don't show first buffer)
if buf_numbers[1] ~= buf_number then
return true
end
end,
offsets = {
{
filetype = "NvimTree",
text = "File Explorer" | function ,
text_align = "left" | "center" | "right"
separator = true
}
},
color_icons = true | false, -- whether or not to add the filetype icon highlights
get_element_icon = function(element)
-- element consists of {filetype: string, path: string, extension: string, directory: string}
-- This can be used to change how bufferline fetches the icon
-- for an element e.g. a buffer or a tab.
-- e.g.
local icon, hl = require('nvim-web-devicons').get_icon_by_filetype(element.filetype, { default = false })
return icon, hl
-- or
local custom_map = {my_thing_ft: {icon = "my_thing_icon", hl}}
return custom_map[element.filetype]
end,
show_buffer_icons = true | false, -- disable filetype icons for buffers
show_buffer_close_icons = true | false,
show_close_icon = true | false,
show_tab_indicators = true | false,
show_duplicate_prefix = true | false, -- whether to show duplicate buffer prefix
duplicates_across_groups = true, -- whether to consider duplicate paths in different groups as duplicates
persist_buffer_sort = true, -- whether or not custom sorted buffers should persist
move_wraps_at_ends = false, -- whether or not the move command "wraps" at the first or last position
-- can also be a table containing 2 custom separators
-- [focused and unfocused]. eg: { '|', '|' }
separator_style = "slant" | "slope" | "thick" | "thin" | { 'any', 'any' },
enforce_regular_tabs = false | true,
always_show_bufferline = true | false,
auto_toggle_bufferline = true | false,
hover = {
enabled = true,
delay = 200,
reveal = {'close'}
},
sort_by = 'insert_after_current' |'insert_at_end' | 'id' | 'extension' | 'relative_directory' | 'directory' | 'tabs' | function(buffer_a, buffer_b)
-- add custom logic
local modified_a = vim.fn.getftime(buffer_a.path)
local modified_b = vim.fn.getftime(buffer_b.path)
return modified_a > modified_b
end,
pick = {
alphabet = "abcdefghijklmopqrstuvwxyzABCDEFGHIJKLMOPQRSTUVWXYZ1234567890",
},
}
}
<
==============================================================================
HOVER EVENTS *bufferline-hover-events*
You can configure bufferline to respond to hover events if you are using
version 0.8 of neovim or higher. In order to enable this feature. You must
first enable the |'mousemoveevent'| vim option and then add the item that you
would like to hide/reveal on hover to your config and set `enable = true` i.e.
NOTE: currently only hiding/revealing the buffer close icon is possible.
>lua
options = {
hover = {
enabled = true,
delay = 200,
reveal = {'close'}
}
}
<
With the above configuration, the hover events will be emitted after hovering for `200ms`
and the close button will be hidden until you hover on it.
==============================================================================
STYLING *bufferline-styling*
You can change the appearance of the bufferline separators by setting the
`separator_style`. The available options are:
* `slant` - Use slanted/triangular separators
* `padded_slant` - Same as `slant` but with extra padding which some terminals require.
If `slant` does not render correctly for you try padded this instead.
* `slope` - Use slanted/triangular separators but slopped to the right
* `padded_slope` - Same as `slope` but with extra padding which some terminals require.
If `slope` does not render correctly for you try padded this instead.
* `thick` - Increase the thickness of the separator characters
* `thin` - (default) Use thin separator characters
* finally you can pass in a custom list containing 2 characters which will be
used as the separators e.g. `{"|", "|"}`, the first is the left and the
second is the right separator
==============================================================================
STYLE PRESETS *bufferline-style-presets*
You also use one of the pre-defined rulesets i.e. preset for the bufferline
e.g. you can remove all bold text by setting the `options.style_preset` to
`require('bufferline').style_preset.no_bold` or `no_italic`.
There are also more stylistic presets such as `minimal` which makes the foreground
match the background so that only the text of the buffers is visible and the
bufferline is more unobtrusive.
e.g.
>lua
local bufferline = require('bufferline')
bufferline.setup({
options = {
style_preset = bufferline.style_preset.no_italic,
-- or you can combine these e.g.
style_preset = {
bufferline.style_preset.no_italic,
bufferline.style_preset.no_bold
},
}
})
<
The available options are
- `no_italic`
- `no_bold`
- `minimal`
==============================================================================
TABPAGES *bufferline-tabpages*
This plugin can also be set to show only tabpages. This can be done by setting
the `mode` option to `tabs`. This will change the bufferline to a tabline it
has a lot of the same features/styling but not all. A few things to note are
* Sorting doesn't work yet as that needs to be thought through.
* Grouping doesn't work yet as that also needs to be thought through.
`BufferLineTabRename`
Tabs can be renamed using the `BufferLineTabRename` command:
e.g.
- Rename the current tab: `BufferLineTabRename Code`
- Rename a tab based on it's `tabnr`: `BufferLineTabRename 1 Code`
==============================================================================
NUMBERS *bufferline-numbers*
You can prefix buffer names with either the `ordinal` or `buffer id`, using
the `numbers` option. Currently this can be specified as either a string of
`buffer_id` | `ordinal` or a function This function allows maximum flexibility
in determining the appearance of this section.
It is passed a table with the following keys:
* `raise` - a helper function to convert the passed number to superscript e.g. `raise(id)`.
* `lower` - a helper function to convert the passed number to subscript e.g. `lower(id)`.
* `ordinal` - The buffer ordinal number.
* `id` - The buffer ID.
>
-- For ⁸·₂
numbers = function(opts)
return string.format('%s·%s', opts.raise(opts.id), opts.lower(opts.ordinal))
end,
-- For ₈.₂
numbers = function(opts)
return string.format('%s.%s', opts.lower(opts.id), opts.lower(opts.ordinal))
end,
-- For 2.)8.) - change the order of arguments to change the order in the string
numbers = function(opts)
return string.format('%s.)%s.)', opts.ordinal, opts.id)
end,
-- For 8|² -
numbers = function(opts)
return string.format('%s|%s', opts.id, opts.raise(opts.ordinal))
end,
<
==============================================================================
LSP DIAGNOSTICS *bufferline-diagnostics*
By setting `diagnostics = "nvim_lsp" | "coc"` you will get an indicator in the
bufferline for a given tab if it has any errors This will allow you to
tell at a glance if a particular buffer has errors. Currently only the
native neovim lsp is supported, mainly because it has the easiest API for
fetching all errors for all buffers (with an attached lsp client) This
feature is _WIP_ so beware and report any issues if you find any.
In order to customise the appearance of the diagnostic count you can pass
a custom function in your setup.
>lua
-- rest of config ...
--- count is an integer representing total count of errors
--- level is a string "error" | "warning"
--- this should return a string
--- Don't get too fancy as this function will be executed a lot
diagnostics_indicator = function(count, level)
local icon = level:match("error") and " " or " "
return " " .. icon .. count
end
<
The highlighting for the filename if there is an error can be changed by
replacing the highlights for `error`, `error_visible`, `error_selected`,
`warning`, `warning_visible`, `warning_selected`.
The diagnostics indicator can be set to `false` to remove the indicators
completely whilst still keeping the highlight of the buffer name.
LSP indicators can additionally be reported conditionally, based on buffer
context. For instance, you could disable reporting LSP indicators for the
current buffer and only have them appear for other buffers.
>lua
diagnostics_indicator = function(count, level, diagnostics_dict, context)
if context.buffer:current() then
return ''
end
return ' '
end
<
==============================================================================
GROUPS *bufferline-groups*
The buffers this plugin shows can be grouped based on a users configuration.
Groups are a way of allowing a user to visualize related buffers in clusters as
well as operating on them together e.g. by clicking the group indicator all
grouped buffers can be hidden. They are partially inspired by google chrome's,
tabs as well as centaur tab's groups.
In order to group buffers specify a list of groups in your config e.g.
>lua
groups = {
options = {
toggle_hidden_on_enter = true -- when you re-enter a hidden group this options re-opens that group so the buffer is visible
},
items = {
{
name = "Tests", -- Mandatory
highlight = {underline = true, sp = "blue"}, -- Optional
priority = 2, -- determines where it will appear relative to other groups (Optional)
icon = " ", -- Optional
matcher = function(buf) -- Mandatory
return buf.filename:match('%_test') or buf.filename:match('%_spec')
end,
},
{
name = "Docs",
highlight = {undercurl = true, sp = "green"},
auto_close = false, -- whether or not close this group if it doesn't contain the current buffer
matcher = function(buf)
return buf.filename:match('%.md') or buf.filename:match('%.txt')
end,
separator = { -- Optional
style = require('bufferline.groups').separator.tab
},
}
}
}
<
==============================================================================
ORDERING GROUPS *bufferline-ordering-groups*
Groups are ordered by their position in the `items` list, the first group shows
at the start of the bufferline and so on. You might want to order groups
around the un-grouped buffers e.g.
>
| group 1 | buf 1 (ungrouped) | buf 2 (ungrouped) | group 2 |
<
In this case built-in groups are provided (for now just the `ungrouped`)
built-in so you can achieve the order above using
>lua
local groups = require('bufferline.groups')
groups = {
items = {
{name = "group 1", ... },
groups.builtin.ungrouped, -- the ungrouped buffers will be in the middle of the grouped ones
{name = "group 2", ...},
}
}
<
==============================================================================
GROUP COMMANDS *bufferline-group-commands*
Grouped buffers can also be interacted with using a few commands namely
* `:BufferLineGroupClose` - which will close all buffers in this group
* `:BufferLineGroupToggle` - which will hide or show a group
Other group related functionality can be implemented using the
`require('bufferline').group_action` API.
e.g.
>lua
function _G.__group_open()
require('bufferline').group_action(, function(buf)
vim.cmd('vsplit '..buf.path)
end)
end
<
==============================================================================
PINNING BUFFERS *bufferline-pinning*
Buffers can be pinned to the start of the bufferline by using the
`:BufferLineTogglePin` command, this will override other groupings or sorting
order for the buffer and position it left of all other buffers.
Pinned buffers are essentially a builtin group that positions the assigned
elements. The icons and highlights for pinned buffers can be changed similarly
to other groups e.g.
>lua
config = {
options = {
groups = {
items = {
require('bufferline.groups').builtin.pinned:with({ icon = " " })
... -- other items
}
}
}
}
<
==============================================================================
REGULAR TAB SIZES *bufferline-regular-tabs*
Generally this plugin enforces a minimum tab size so that the buffer line
appears consistent. Where a tab is smaller than the tab size it is padded.
If it is larger than the tab size it is allowed to grow up to the max name
length specified (+ the other indicators). If you set
`enforce_regular_tabs = true` tabs will be prevented from extending beyond
the tab size and all tabs will be the same length
NOTE: when this option is set to `true`. It will disable the ability to
deduplicate buffers.
==============================================================================
SORTING *bufferline-sorting*
Bufferline allows you to sort the visible buffers by `extension` or `directory`: >vim
" Using vim commands
:BufferLineSortByExtension
:BufferLineSortByDirectory
:BufferLineSortByTabs
-- Or using lua functions
:lua require'bufferline'.sort_by('extension')`
:lua require'bufferline'.sort_by('directory')`
:lua require'bufferline'.sort_by('tabs')`
By default bufferline will sort by buffer number which is an integer value
provided by vim to identify a buffer that increases as new buffers are opened
this means that new buffers are placed at the end of the bufferline.
For more advanced usage you can provide a custom compare function which
will receive two buffers to compare. You can see what fields
are available to use using >lua
sort_by = function(buffer_a, buffer_b)
print(vim.inspect(buffer_a))
-- add custom logic
local modified_a = vim.fn.getftime(buffer_a.path)
local modified_b = vim.fn.getftime(buffer_b.path)
return modified_a > modified_b
end
<
When using a sorted bufferline it's advisable that you use the
`BufferLineCycleNext` and `BufferLineCyclePrev` commands since these will
traverse the bufferline bufferlist in order whereas `bnext` and `bprev` will
cycle buffers according to the buffer numbers given by vim.
==============================================================================
FILTERING *bufferline-filtering*
Bufferline can be configured to take a custom filtering function via the
`custom_filter` option. This value must be a lua function that will receive
each buffer number that is going to be used for the bufferline, as well as all the others.
A user can then check whatever they would like and return `true` if they would like it to
appear and `false` if not.
For example: >lua
custom_filter = function(buf, buf_nums)
-- dont show help buffers in the bufferline
return not vim.bo[buf].filetype == "help" then
-- you can use more custom logic for example
-- don't show files matching a pattern
return not vim.fn.bufname(buf):match('test')
-- show only certain filetypes in certain tabs e.g. js in one, css in
another etc.
local tab_num = vim.fn.tabpagenr()
if tab_num == 1 and vim.bo[buf].filetype == "javascript" then
return true
elseif tab_num == 2 and vim.bo[buf].filetype == "css" then
return true
else
return false
end
-- My personal example:
-- Don't show output log buffers in the same tab as my other code.
-- 1. Check if there are any log buffers in the full list of buffers
-- if not don't do any filtering
local logs =
vim.tbl_filter(
function(b)
return vim.bo[b].filetype == "log"
end,
buf_nums
)
if vim.tbl_isempty(logs) then
return true
end
-- 2. if there are log buffers then only show the log buffer
local tab_num = vim.fn.tabpagenr()
local is_log = vim.bo[buf].filetype == "log"
-- only show log buffers in secondary tabs
return (tab_num == 2 and is_log) or (tab_num ~= 2 and not is_log)
end
<
==============================================================================
COMMANDS *bufferline-commands*
Bufferline includes a few commands to allow deleting buffers. These commands
are:
* `BufferLineCloseRight` - close all visible buffers to the right of the
current buffer
* `BufferLineCloseLeft` - close all visible buffers to the left of the current
buffer
* `BufferLineCloseOthers` - close all other visible buffers
These commands apply the configured `close_command` to each of the corresponding buffers.
==============================================================================
CUSTOM-FUNCTIONS *bufferline-functions*
A user can also execute arbitrary functions against a buffer using the
`exec` function. For example
>lua
require('bufferline').exec(
4, -- the forth visible buffer from the left
user_function -- an arbitrary user function which gets passed the buffer
)
-- e.g.
function _G.bdel(num)
require('bufferline').exec(num, function(buf, visible_buffers)
vim.cmd('bdelete '..buf.id)
end)
end
vim.cmd [[
command -count Bdel lua _G.bdel()
]]
==============================================================================
SIDEBAR OFFSET *bufferline-offset*
You can prevent the bufferline drawing above a *vertical* sidebar split such as a file explorer.
To do this you must set the `offsets` configuration option to a list of tables
containing the details of the window to avoid. *NOTE:* this is only relevant
for left or right aligned sidebar windows such as `NvimTree`, `NERDTree` or
`Vista`
>lua
offsets = {
{
filetype = "NvimTree",
text = "File Explorer",
highlight = "Directory",
separator = true -- use a "true" to enable the default, or set your own character
}
}
<
The `filetype` is used to check whether a particular window is a match, the
`text` is *optional* and will show above the window if specified.
`text` can be either a string or a function which should also return a string.
See the example below.
>lua
offsets = {
{
filetype = "NvimTree",
text = function()
return vim.fn.getcwd()
end,
highlight = "Directory",
text_align = "left"
}
}
If it is too long it will be truncated. The highlight controls what highlight
is shown above the window.
You can also change the alignment of the text in the offset section using
`text_align` which can be set to `left`, `right` or `center`.
An offset can also have a separator which mimics the appearance of the
win separator, and the intent is give a vertical split the appearance of
a consistent separator. The highlight can be changed using the `offset_separator`
highlight. The value can be set to a `boolean` (uses the default separator if
true) or to a string which will be the character that will be used.
Lastly you can specify a `padding` option as well which will increase the
amount the bufferline is offset beyond just the window width, this isn't
something that is generally required though.
==============================================================================
BUFFERLINE PICK *bufferline-pick*
Using the `BufferLinePick` command will allow for easy selection of a buffer
in view. Trigger the command, using `:BufferLinePick` or better still map this
to a key, e.g. >vim
nnoremap gb :BufferLinePick
<
then pick a buffer by typing the character for that specific buffer that
appears
This functionality can also be used to close a buffer using
`BufferLinePickClose` by triggering this command the same selection UI will
appear but on selecting a buffer it will be closed.
this can also be mapped to something like
>vim
nnoremap gD :BufferLinePickClose
>
You can configure the characters used for selecting buffers using the
`pick.alphabet` option. By default, both uppercase and lowercase
alphanumeric characters are used.
>lua
options = {
pick = {
alphabet = "abcdefghijklmopqrstuvwxyz"
}
}
<
With the configuration above, bufferline will only use lowercase letters.
==============================================================================
MOUSE ACTIONS *bufferline-mouse-actions*
You can configure different type of mouse clicks to behave differently. The
current mouse click types are
* Left - `left_mouse_command`
* Right - `right_mouse_command`
* Middle - `middle_mouse_command`
* Close - `close_command`
Currently left mouse opens the selected buffer but the command can be tweaked
using `left_mouse_command` which can be specified as either a lua function or
string which uses lua's printf style string formatting (https://www.lua.org/pil/20.html)
e.g. `buffer %d`
You can do things like open a vertical split on right clicking the buffer name
for example using.
>lua
right_mouse_command = "vertical sbuffer %d"
<
Or you can set the value to a function and handle the click action however you
please for example you can use another plugin such as `bufdelete.nvim`
(https://github.com/famiu/bufdelete.nvim) to handle closing the buffer using
the `close_command`.
>lua
left_mouse_command = function(bufnum)
require('bufdelete').bufdelete(bufnum, true)
end
<
You can also set this value to an empty string or to `false` to disable the
action.
==============================================================================
MAPPINGS *bufferline-mappings*
`BufferLineGoToBuffer`
You can select a buffer by it's visible position in the bufferline using the `BufferLineGoToBuffer`
command. This means that if you have 60 buffers open but only 7 visible in the bufferline
using `BufferLineGoToBuffer 4` will go to the 4th visible buffer but not necessarily the 5th in the
absolute list of open buffers. To select the last visible buffer, you can also use `BufferLineGoToBuffer -1`.
>
<- (30) | buf31 | buf32 | buf33 | buf34 | buf35 | buf36 | buf37 (24) ->
<
Using `BufferLineGoToBuffer 4` will open `buf34` as it is the 4th visible buffer.
This can then be mapped using
>vim
nnoremap 1 BufferLineGoToBuffer 1
nnoremap 2 BufferLineGoToBuffer 2
nnoremap 3 BufferLineGoToBuffer 3
nnoremap 4 BufferLineGoToBuffer 4
nnoremap 5 BufferLineGoToBuffer 5
nnoremap 6 BufferLineGoToBuffer 6
nnoremap 7 BufferLineGoToBuffer 7
nnoremap 8 BufferLineGoToBuffer 8
nnoremap 9 BufferLineGoToBuffer 9
nnoremap $ BufferLineGoToBuffer -1
<
If you'd rather map these yourself, use:
>vim
nnoremap mymap :lua require"bufferline".go_to(num)
Alternatively, if you want to instead jump to the absolute position of the
buffer in the bufferline (as displayed by the ordinal buffer numbers), you can
use the `lua` API to set it up using `require'bufferline'.go_to(number, absolute)`,
where absolute is a boolean that determines whether to use the
absolute buffer position or the visible/relative one.
>vim
nnoremap 1 lua require("bufferline").go_to(1, true)
nnoremap 2 lua require("bufferline").go_to(2, true)
nnoremap 3 lua require("bufferline").go_to(3, true)
nnoremap 4 lua require("bufferline").go_to(4, true)
nnoremap 5 lua require("bufferline").go_to(5, true)
nnoremap 6 lua require("bufferline").go_to(6, true)
nnoremap 7 lua require("bufferline").go_to(7, true)
nnoremap 8 lua require("bufferline").go_to(8, true)
nnoremap 9 lua require("bufferline").go_to(9, true)
nnoremap $ lua require("bufferline").go_to(-1, true)
<
You can close buffers by clicking the close icon or by right clicking the tab anywhere
A few of this plugins commands can be mapped for ease of use. >vim
" These commands will navigate through buffers in order
" regardless of which mode you are using e.g. if you change
" the order of buffers :bnext and :bprevious will not respect the custom ordering
nnoremap [b :BufferLineCycleNext
nnoremap b] :BufferLineCyclePrev
" These commands will move the current buffer backwards or forwards in the bufferline
nnoremap :BufferLineMoveNext
nnoremap :BufferLineMovePrev
" These commands will move the current buffer to the first or the last position in the bufferline
nnoremap :lua require'bufferline'.move_to(1)
nnoremap :lua require'bufferline'.move_to(-1)
" These commands will sort buffers by directory, language, or a custom criteria
nnoremap be :BufferLineSortByExtension
nnoremap bd :BufferLineSortByDirectory
nnoremap :lua require'bufferline'.sort_by(function (buf_a, buf_b) return buf_a.id < buf_b.id end)
If you manually arrange your buffers using `:BufferLineMove{Prev|Next}` during an nvim session this can be persisted for the session.
This is enabled by default but you need to ensure that your `sessionoptions+=globals` otherwise the session file will
not track global variables which is the mechanism used to store your sort order.
==============================================================================
HIGHLIGHTS *bufferline-highlights*
When `termguicolors` is enabled, this plugin is designed to work automatically,
deriving colours from the user's theme, you can change highlight groups by
overriding the section you'd like to change.
Keep in mind that despite my best efforts not to change these they might
require the occasional tweak (if you don't customise these too much you should
be fine 🤞).
Highlight values can also be specified as tables with a key of the highlight
name e.g. `Normal` and the attribute which is one of `fg`, `bg`. See the
`{what}` argument of `:h synIDAttr` for details, but only these 2 have been
tested
for example: >lua
highlights = {
fill = {
bg = {
attribute = "fg",
highlight = "Pmenu"
}
}
}
<
This will automatically pull the value of `Pmenu` fg colour and use it
Any improperly specified tables will be set to `nil` and overriden with the
default value for that key.
NOTE: you can specify colors the same way you specify colors for
`nvim_set_hl`. See `:h vim.api.nvim_set_hl` .
>lua
require('bufferline').setup({
highlights = {
fill = {
fg = '',
bg = '',
},
background = {
fg = '',
bg = '',
},
tab = {
fg = '',
bg = '',
},
tab_selected = {
fg = '',
bg = '',
},
tab_separator = {
fg = '',
bg = '',
},
tab_separator_selected = {
fg = '',
bg = '',
sp = '',
underline = '',
},
tab_close = {
fg = '',
bg = '',
},
close_button = {
fg = '',
bg = '',
},
close_button_visible = {
fg = '',
bg = '',
},
close_button_selected = {
fg = '',
bg = '',
},
buffer_visible = {
fg = '',
bg = '',
},
buffer_selected = {
fg = '',
bg = '',
bold = true,
italic = true,
},
numbers = {
fg = '',
bg = '',
},
numbers_visible = {
fg = '',
bg = '',
},
numbers_selected = {
fg = '',
bg = '',
bold = true,
italic = true,
},
diagnostic = {
fg = '',
bg = '',
},
diagnostic_visible = {
fg = '',
bg = '',
},
diagnostic_selected = {
fg = '',
bg = '',
bold = true,
italic = true,
},
hint = {
fg = '',
sp = '',
bg = '',
},
hint_visible = {
fg = '',
bg = '',
},
hint_selected = {
fg = '',
bg = '',
sp = '',
bold = true,
italic = true,
},
hint_diagnostic = {
fg = '',
sp = '',
bg = '',
},
hint_diagnostic_visible = {
fg = '',
bg = '',
},
hint_diagnostic_selected = {
fg = '',
bg = '',
sp = '',
bold = true,
italic = true,
},
info = {
fg = '',
sp = '',
bg = '',
},
info_visible = {
fg = '',
bg = '',
},
info_selected = {
fg = '',
bg = '',
sp = '',
bold = true,
italic = true,
},
info_diagnostic = {
fg = '',
sp = '',
bg = '',
},
info_diagnostic_visible = {
fg = '',
bg = '',
},
info_diagnostic_selected = {
fg = '',
bg = '',
sp = '',
bold = true,
italic = true,
},
warning = {
fg = '',
sp = '',
bg = '',
},
warning_visible = {
fg = '',
bg = '',
},
warning_selected = {
fg = '',
bg = '',
sp = '',
bold = true,
italic = true,
},
warning_diagnostic = {
fg = '',
sp = '',
bg = '',
},
warning_diagnostic_visible = {
fg = '',
bg = '',
},
warning_diagnostic_selected = {
fg = '',
bg = '',
sp = '',
bold = true,
italic = true,
},
error = {
fg = '',
bg = '',
sp = '',
},
error_visible = {
fg = '',
bg = '',
},
error_selected = {
fg = '',
bg = '',
sp = '',
bold = true,
italic = true,
},
error_diagnostic = {
fg = '',
bg = '',
sp = '',
},
error_diagnostic_visible = {
fg = '',
bg = '',
},
error_diagnostic_selected = {
fg = '',
bg = '',
sp = '',
bold = true,
italic = true,
},
modified = {
fg = '',
bg = '',
},
modified_visible = {
fg = '',
bg = '',
},
modified_selected = {
fg = '',
bg = '',
},
duplicate_selected = {
fg = '',
bg = '',
italic = true,
},
duplicate_visible = {
fg = '',
bg = '',
italic = true,
},
duplicate = {
fg = '',
bg = '',
italic = true,
},
separator_selected = {
fg = '',
bg = '',
},
separator_visible = {
fg = '',
bg = '',
},
separator = {
fg = '',
bg = '',
},
indicator_visible = {
fg = '',
bg = '',
},
indicator_selected = {
fg = '',
bg = '',
},
pick_selected = {
fg = '',
bg = '',
bold = true,
italic = true,
},
pick_visible = {
fg = '',
bg = '',
bold = true,
italic = true,
},
pick = {
fg = '',
bg = '',
bold = true,
italic = true,
},
offset_separator = {
fg = '