Home

Awesome

<!-- markdownlint-configure-file { "line-length": false } -->

ARCHIVED

I'm no longer using buftabline.nvim and don't plan on updating it, so I'm archiving this repository. I found that I was spending too much of my time managing my open buffers (something Vim doesn't want you to do) and that using standard tabpages and switching buffers via Telescope / FZF vastly sped up my editing. Adjusting to this workflow took time, but I recommend trying it before resorting to a buffer tabline plugin like this one.

To my knowledge, everything in this plugin works, so if it fits your needs, feel free to use it as-is or fork it.

buftabline.nvim

A low-config, minimalistic buffer tabline Neovim plugin written in Lua, shamelessly inspired by vim-buftabline.

Screen Shot 2021-08-25 at 3 30 42 PM

Setup

Install using your favorite plugin manager and call the following Lua code somewhere in your configuration:

require("buftabline").setup {}

If you're using packer.nvim, you can install and set up buftabline simultaneously:

use {
    "jose-elias-alvarez/buftabline.nvim",
    requires = {"kyazdani42/nvim-web-devicons"}, -- optional!
    config = function() require("buftabline").setup {} end
}

Features

Buftabline shows your open buffers in your tabline with (optional) filetype icons and applies highlighting to each tab based its buffer's state. If you want, it'll also show your tabpages (:help tabpages). That's pretty much it.

For convenience, the plugin exposes a function, buftarget(number, command) which will target a buffer in the tabline with a command:

require("buftabline").buftarget(1, "rightbelow sb")

By default, the plugin maps <Leader>0-9 to go to the corresponding buffer (0 gets converted to 10), but you can disable this by setting go_to_maps to false (see Options).

To simplify the creation of more custom commands, buftabline also exposes a map method. The following example will map <Leader>c1 through Leader<c9> to the corresponding bdelete command:

require("buftabline").map({ prefix = "<Leader>c", cmd = "bdelete" })

Lastly, the plugin adds the following Vim commands:

Options

For most users, everything should work out-of-the-box, but the plugin exposes the following options (defaults shown):

local options = {
    tab_format = " #{n}: #{b}#{f} ",
    buffer_id_index = false,
    icon_colors = true,
    start_hidden = false,
    auto_hide = false,
    disable_commands = false,
    go_to_maps = true,
    flags = {
        modified = " [+]",
        not_modifiable = " [-]",
        readonly = " [RO]",
    },
    hlgroups = {
        current = "TabLineSel",
        normal = "TabLine",
        active = nil,
        spacing = nil,
        modified_current = nil,
        modified_normal = nil,
        modified_active = nil,
        tabpage_current = nil,
        tabpage_normal = nil,
    },
    show_tabpages = true,
    tabpage_format = " #{n} ",
    tabpage_position = "right",
}
OptionDescription
tab_formatDefines how the plugin formats buffer tabs (see Format below for details).
buffer_id_indexUses buffer numbers (the ones shown in :ls) instead of sequential indexes.
icon_colorsShows icon colors in your tabline. Can be true (always show), current (show for current tab), and normal (show for background tabs).
start_hiddenHides the tabline when Neovim starts.
auto_hideShows the tabline when you have more than one buffer open and hides it when you don't. Not compatible with start_hidden.
disable_commandsStops the plugin from defining commands.
go_to_mapsMaps <Leader>0-9 to go to the corresponding buffer.
flagsSets the flags used to mark a buffer's status.
hlgroupsSets highlight groups (see Colors below for details).
show_tabpagesShows tabpages (:h tabpages) in your bufferline. Can be true (show if more than one tabpage), always (always show), and false (disable). If you don't use tabpages, there's no need to change this.
tabpage_formatDefines how the plugin formats tabpages (see Format below for details).
tabpage_positionDetermines where the plugin shows tabpages. Can be right or left. Does nothing if you've set show_tabpages to false.

Format

The tab_format string accepts the following special options and replaces them with the corresponding buffer information. The plugin won't do anything to other characters, including spaces and separators.

OptionInformation
#{n}The buffer's index. Modified by buffer_id_index.
#{b}The buffer's filename. If two or more buffers share a filename, it'll add the name of each buffer's enclosing directory.
#{f}The buffer's flags (modified, modifiable, and read-only).
#{i}The buffer's filetype icon.

The tabpage_format string accepts the following option:

OptionInformation
#{n}The tabpage's index.

Colors

The hlgroups option is a table that accepts the following keys to allow setting highlight groups based on buffer state. Leaving a value empty will cause the plugin to fall back to the next available group.

KeyCondition
currentThe current buffer.
normalThe buffer is not current visible in any window.
activeThe buffer is visible in another window.
spacingApplied to the empty space between buffer tabs and any right-aligned tabs (or the end of the viewport).
modified_currentSame as current, but the buffer is modified.
modified_normalSame as normal, but the buffer is modified.
modified_activeSame as active, but the buffer is modified.
tabpage_currentThe current tabpage. Falls back to current if not defined.
tabpage_normalTabpages other than the current. Falls back to normal if not defined.

FAQ

How do I enable icons?

Add #{i} to tab_format. For example, to keep the default format but show icons after the buffer's filename:

tab_format = " #{n}: #{b}#{f} #{i} "

Non-goals

Aside from these, I'm open to PRs.

Tests

Run make test from the plugin's root directory. Depends on plenary.nvim.

Inspiration