Skip to content

A low-config, minimalistic buffer tabline Neovim plugin written in Lua.

License

Notifications You must be signed in to change notification settings

lucassperez/buftabline.nvim

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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:

  • :ToggleBuftabline (useful for smaller screens / focus sessions)

  • :BufNext and :BufPrev (like :bnext and :bprev, but they correspond to bufferline indexes.

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",
}
Option Description
tab_format Defines how the plugin formats buffer tabs (see Format below for details).
buffer_id_index Uses buffer numbers (the ones shown in :ls) instead of sequential indexes.
icon_colors Shows icon colors in your tabline. Can be true (always show), current (show for current tab), and normal (show for background tabs).
start_hidden Hides the tabline when Neovim starts.
auto_hide Shows the tabline when you have more than one buffer open and hides it when you don't. Not compatible with start_hidden.
disable_commands Stops the plugin from defining commands.
go_to_maps Maps <Leader>0-9 to go to the corresponding buffer.
flags Sets the flags used to mark a buffer's status.
hlgroups Sets highlight groups (see Colors below for details).
show_tabpages Shows 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_format Defines how the plugin formats tabpages (see Format below for details).
tabpage_position Determines 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.

Option Information
#{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:

Option Information
#{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.

Key Condition
current The current buffer.
normal The buffer is not current visible in any window.
active The buffer is visible in another window.
spacing Applied to the empty space between buffer tabs and any right-aligned tabs (or the end of the viewport).
modified_current Same as current, but the buffer is modified.
modified_normal Same as normal, but the buffer is modified.
modified_active Same as active, but the buffer is modified.
tabpage_current The current tabpage. Falls back to current if not defined.
tabpage_normal Tabpages 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

  • Vim support. Use vim-buftabline!
  • Mouse support.
  • Visual customization beyond what's available now.

Aside from these, I'm open to PRs.

Tests

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

Inspiration

  • vim-buftabline, the direct inspiration for this plugin and still a solid plugin.

  • nvim-bufbar by @ojroques, who directed me to his plugin and encouraged me to use it as a starting point.

  • lightline-bufferline, which gave me the idea to "target" buffers in the tabline with commands.

  • nvim-bufferline and barbar.nvim, two tabline plugins that are far and away better than this one but are a little too much for my simple needs. (Thanks to barbar.nvim for its implementation of colored icons, which provided the basis for the implementation in this plugin.)

About

A low-config, minimalistic buffer tabline Neovim plugin written in Lua.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Lua 99.0%
  • Other 1.0%