Repository files navigation

Asnazzy 💅 buffer line (with tabpage integration) for Neovim built usinglua.

• Requirements
• Installation
• Usage
• Configuration
• Features
  • Alternate styling
  • Hover events
  • Underline indicator
  • Tabpages
  • LSP indicators
  • Groups
  • Sidebar offsets
  • Numbers
  • Picking
  • Pinning
  • Unique names
  • Close icons
  • Re-ordering
  • Custom areas
• How do I see only buffers per tab?
• Caveats
• FAQ

This plugin shamelessly attempts to emulate the aesthetics of GUI text editors/Doom Emacs.It was inspired by a screenshot of DOOM Emacs usingcentaur tabs.

• Neovim 0.8+
• A patched font (seenerd fonts)
• A colorscheme (either your custom highlight or a maintained one somewhere)

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 totag = "v1.*"

Lua

-- using packer.nvimuse {'akinsho/bufferline.nvim',tag="*",requires='nvim-tree/nvim-web-devicons'}-- using lazy.nvim{'akinsho/bufferline.nvim',version="*",dependencies='nvim-tree/nvim-web-devicons'}

Vimscript

Plug'nvim-tree/nvim-web-devicons'" Recommended (for coloured icons)" Plug 'ryanoasis/vim-devicons' Icons without coloursPlug'akinsho/bufferline.nvim', {'tag':'*' }

See the docs for details:h bufferline.nvim

You need to be usingtermguicolors for this plugin to work, as it reads the hexgui color valuesof various highlight groups.

Vimscript

" In your init.lua or init.vimsettermguicolorslua << EOFrequire("bufferline").setup{}EOF

Lua

vim.opt.termguicolors=truerequire("bufferline").setup{}

You can close buffers by clicking the close icon or byright clicking the tab anywhere

for more details on how to configure this plugin in details please see:h bufferline-configuration

• Colours derived from colorscheme where possible.

• Sort buffers byextension,directory or pass in a custom compare function

• Configuration via lua functions for greater customization.

NOTE: some terminals require special characters to be padded so set the style topadded_slant if the appearance isn't right in your terminal emulator. Please keep in mindthough that results may vary depending on your terminal emulator of choice and this style might not work for all terminals

see::h bufferline-styling

NOTE: this isonly available for >= neovim 0.8+

see:help bufferline-hover-events for more information on configuration

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 increasedunderline thickness and an increased underline position so it sits further from the text

This plugin can also be set to show only tabpages. This can be done by setting themode option totabs. This will change the bufferline to a tablineit 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.

By settingdiagnostics = "nvim_lsp" | "coc" you will get an indicator in the bufferline for a given tab if it has any errorsThis 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.

-- 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 lotdiagnostics_indicator=function(count,level,diagnostics_dict,context)localicon=level:match("error")and""or""return""..icon..countend

diagnostics_indicator=function(count,level,diagnostics_dict,context)locals=""fore,ninpairs(diagnostics_dict)dolocalsym=e=="error"and""or (e=="warning"and""or"")s=s..n..symendreturnsend

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.

diagnostics_indicator=function(count,level,diagnostics_dict,context)ifcontext.buffer:current()thenreturn''endreturn''end

The first bufferline showsdiagnostic.lua as the currently openedcurrent buffer. It has LSP reported errors, but they don't show up in the bufferline.The second bufferline shows500-nvim-bufferline.lua as the currently openedcurrent buffer. Because the 'faulty'diagnostic.lua buffer has now transitioned fromcurrent tovisible, the LSP indicator does show up.

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 clustersas well as operating on them together e.g. by clicking the group indicator all grouped buffers can be hidden. They are partially inspired bygoogle chrome's tabs as well as centaur tab's groups.

see:help bufferline-groups for more information on how to set these up

You can prefix buffer names with either theordinal orbuffer id, using thenumbers option.Currently this can be specified as either a string ofbuffer_id |ordinal or a function

see:help bufferline-numbers for more details

This order can be persisted between sessions (enabled by default).

see:help bufferline-custom-areas

This behaviour isnot native in neovim there is no internal concept of localised buffers to tabs asthat 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 usingscope.nvim with this plugin. Although I believe a betterlong-term solution for users who want this functionality is to ask for real native supportfor this upstream.

• This won't appeal to everyone's tastes. This plugin is opinionated about how the tablinelooks, 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 schemei.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 ormanually 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 ofthis plugin won't really work as intended since it depends on darkening things.

• Why isn't the bufferline appearing?

  The most common reason for this that has come up in various issues is it clashes withanother plugin. Please make sure that you do not have another bufferline plugin installed.

  If you are usingairline make sure you setlet g:airline#extensions#tabline#enabled = 0.If you are usinglightline 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, thatGuiTablineis disabled. For this create a file calledginit.vim in your nvim config directory and put the lineGuiTabline 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 bybuftablines's author.Please read this for a more comprehensive answer to this question. The short answer to this isbuffers represent files in nvim and tabs, a collection of windows (or just one). Vim natively allows visualising tabs i.e. collectionsof window, but not just the files that are open. There areendless debates on this topic, but allowing a user to see what files theyhave 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.