ranelpadon/lightline-bufferline

A lightweight plugin to display the list of buffers in the lightline vim plugin

lightline-bufferline

This plugin provides bufferline functionality for the lightline vim plugin.

Table Of Contents

• Installation
• Integration
• Configuration
• Mappings
• Example
• License

Installation

Installation can be easily done with a plugin manager of your choice. For example vim-plug:

Plug 'mengelbrecht/lightline-bufferline'

Integration

1. Add 'buffers' to g:lightline.tabline.
2. Add 'buffers': 'lightline#bufferline#buffers' to g:lightline.component_expand.
3. Add 'buffers': 'tabsel' to g:lightline.component_type.

The result looks for example like this:

let g:lightline = {
      \ 'colorscheme': 'one',
      \ 'active': {
      \   'left': [ [ 'mode', 'paste' ], [ 'readonly', 'filename', 'modified' ] ]
      \ },
      \ 'tabline': {
      \   'left': [ ['buffers'] ],
      \   'right': [ ['close'] ]
      \ },
      \ 'component_expand': {
      \   'buffers': 'lightline#bufferline#buffers'
      \ },
      \ 'component_type': {
      \   'buffers': 'tabsel'
      \ }
      \ }

If you are using neovim with a lua configuration the above example looks like this:

vim.g['lightline'] = {
  colorscheme = 'one',
  active = {
    left = {{'mode', 'paste'}, {'readonly', 'filename', 'modified'}}
  },
  tabline = {
    left = {{'buffers'}},
    right = {{'close'}}
  },
  component_expand = {
    buffers = 'lightline#bufferline#buffers'
  },
  component_type = {
    buffers = 'tabsel'
  }
}

If you're adding the buffers to the bottom statusbar, the modified indicator will not be updated immediately. To work around this, add this autocmd to your vim config:

autocmd BufWritePost,TextChanged,TextChangedI * call lightline#update()

Configuration

g:lightline#bufferline#filename_modifier

The filename-modifier applied to each buffer name. Default is ':.'. To see the available options use the command :help filename-modifiers in vim.

g:lightline#bufferline#modified

The indicator to use for a modified buffer. Default is ' +'.

g:lightline#bufferline#more_buffers

The indicator to use when there are buffers that are not shown on the bufferline because they didn't fit the available space. Default is ....

g:lightline#bufferline#read_only

The indicator to use for a read-only buffer. Default is ' -'.

g:lightline#bufferline#shorten_path

Defines whether to shorten the path using the pathshorten function. Default is 1.

g:lightline#bufferline#smart_path

If enabled, when two files have the same name the distinguishing sections of each file's path are added. Default is 1.

g:lightline#bufferline#show_number

Defines whether to add the buffer number to the buffer name. Default is 0. Valid values are:

• 0: No numbers
• 1: Buffer number as shown by the :ls command
• 2: Ordinal number (buffers are numbered from 1 to n sequentially)
• 3: Both buffer number and ordinal number next to each other
• 4: Both buffer number and ordinal number next to each other, where the oridinal number is shown before buffer number

For ordinal number in option 2, 3 and 4, number maps g:lightline#bufferline#number_map and g:lightline#bufferline#composed_number_map are used as described below.

g:lightline#bufferline#composed_number_map

Dictionary mapping ordinal numbers to their alternative character representations. Default is {}.

For example, to use parenthized unicode numbers taken from Enclosed Alphanumerics Unicode block:

let g:lightline#bufferline#composed_number_map = {
\ 1:  '⑴ ', 2:  '⑵ ', 3:  '⑶ ', 4:  '⑷ ', 5:  '⑸ ',
\ 6:  '⑹ ', 7:  '⑺ ', 8:  '⑻ ', 9:  '⑼ ', 10: '⑽ ',
\ 11: '⑾ ', 12: '⑿ ', 13: '⒀ ', 14: '⒁ ', 15: '⒂ ',
\ 16: '⒃ ', 17: '⒄ ', 18: '⒅ ', 19: '⒆ ', 20: '⒇ '}

Note: The option only applies when g:lightline#bufferline#show_number is set to 2 or 3.

g:lightline#bufferline#number_map

Fallback dictionary mapping digits (0-9) which are used in ordinal number composing if the number is not mapped in g:lightline#bufferline#composed_number_map. Default is {}.

For example, to use unicode superscript numerals:

let g:lightline#bufferline#number_map = {
\ 0: '⁰', 1: '¹', 2: '²', 3: '³', 4: '⁴',
\ 5: '⁵', 6: '⁶', 7: '⁷', 8: '⁸', 9: '⁹'}

... or unicode subscript numerals:

let g:lightline#bufferline#number_map = {
\ 0: '₀', 1: '₁', 2: '₂', 3: '₃', 4: '₄',
\ 5: '₅', 6: '₆', 7: '₇', 8: '₈', 9: '₉'}

Note: The option only applies when g:lightline#bufferline#show_number is set to 2 or 3.

g:lightline#bufferline#number_separator

Defines the string which is used to separate the buffer number (if enabled) and the buffer name. Default is ' '.

g:lightline#bufferline#ordinal_separator

Defines the string which is used to separate the buffer number and the oridinal number. Default is ''.

g:lightline#bufferline#unnamed

The name to use for unnamed buffers. Default is '*'.

g:lightline#bufferline#enable_devicons

Enables the usage of vim-devicons or nvim-web-devicons to display a filetype icon for the buffer. Default is 0.

g:lightline#bufferline#enable_nerdfont

Enables the usage of nerdfont.vim to display a filetype icon for the buffer. Default is 0.

g:lightline#bufferline#icon_position

Defines the position of the filetype icon. Default is left. Valid values are:

• left: Left of the buffer name and after the buffer number
• right: Right of the buffer name
• first: Left of the buffer name and number

g:lightline#bufferline#unicode_symbols

Use unicode symbols for modified and read-only buffers as well as the more buffers indicator. Default is 0.

If set to 1 the symbols +, - and ... are replaced by ✎,  and ….

Note: The symbols are only correctly displayed if your font supports these characters.

g:lightline#bufferline#auto_hide

Automatically hides the bufferline n milliseconds after switching the buffer. For example to show the bufferline for 4 seconds when switching the buffer and hide it afterwards use the following setting:

let g:lightline#bufferline#auto_hide = 4000

Default is 0 and disables the auto-hide behaviour.

g:lightline#bufferline#min_buffer_count

Hides the bufferline by default and shows it if there are n or more buffers. Default is 0 and the bufferline is always shown. If min_tab_count is also specified the bufferline will be shown if one of the conditions is met.

g:lightline#bufferline#min_tab_count

Hides the bufferline by default and shows it if there are n or more tabs. Default is 0 and the bufferline is always shown. If min_buffer_count is also specified the bufferline will be shown if one of the conditions is met. This option can be useful if you are also displaying tabs in the lightline tabline.

g:lightline#bufferline#filter_by_tabpage

When more than one tab is opened, only buffers that are open in a window within the current tab are shown. When there is only one tab, all buffers are shown. Default is 0. This option can be useful if you are also displaying tabs in the lightline tabline.

g:lightline#bufferline#margin_left

The number of spaces to add on the left side of the buffer name. Default is 0.

g:lightline#bufferline#margin_right

The number of spaces to add on the right side of the buffer name. Default is 0.

g:lightline#bufferline#reverse_buffers

If enabled the buffers will be displayed in a reversed order. Default is 0 (buffers are not reversed).

g:lightline#bufferline#right_aligned

If the bufferline is used in the right component of the tabline this should be set to 1 to ensure the correct order of the buffers. Default is 0.

g:lightline#bufferline#clickable

If set to 1 the bufferline is clickable under Neovim versions with tablineat feature. To enable this feature, you must also set the bufferline component to be raw in your vimrc:

let g:lightline.component_raw = {'buffers': 1}

You could provide additional command before the click handler is executed. For example, to always open the buffer in the right/main window even when the file explorer window is on focus.

let g:click_handler_pre_command = 'wincmd l'

Mappings

This plugin provides Plug mappings to switch to buffers using their ordinal number in the bufferline. To display the ordinal numbers in the bufferline use the setting g:lightline#bufferline#show_number = 2.

To use the Plug mappings you can use e.g. these mappings:

nmap <Leader>1 <Plug>lightline#bufferline#go(1)
nmap <Leader>2 <Plug>lightline#bufferline#go(2)
nmap <Leader>3 <Plug>lightline#bufferline#go(3)
nmap <Leader>4 <Plug>lightline#bufferline#go(4)
nmap <Leader>5 <Plug>lightline#bufferline#go(5)
nmap <Leader>6 <Plug>lightline#bufferline#go(6)
nmap <Leader>7 <Plug>lightline#bufferline#go(7)
nmap <Leader>8 <Plug>lightline#bufferline#go(8)
nmap <Leader>9 <Plug>lightline#bufferline#go(9)
nmap <Leader>0 <Plug>lightline#bufferline#go(10)

Additionally you can use the following e.g. to delete buffers by their ordinal number.

nmap <Leader>c1 <Plug>lightline#bufferline#delete(1)
nmap <Leader>c2 <Plug>lightline#bufferline#delete(2)
nmap <Leader>c3 <Plug>lightline#bufferline#delete(3)
nmap <Leader>c4 <Plug>lightline#bufferline#delete(4)
nmap <Leader>c5 <Plug>lightline#bufferline#delete(5)
nmap <Leader>c6 <Plug>lightline#bufferline#delete(6)
nmap <Leader>c7 <Plug>lightline#bufferline#delete(7)
nmap <Leader>c8 <Plug>lightline#bufferline#delete(8)
nmap <Leader>c9 <Plug>lightline#bufferline#delete(9)
nmap <Leader>c0 <Plug>lightline#bufferline#delete(10)

Functions

This plugin provides some public functions to operate with buffers using their ordinal number.

lightline#bufferline#get_ordinal_number_for_buffer(buffer)

This function returns the ordinal number for the given buffer or -1 if the buffer is not found.

lightline#bufferline#get_buffer_for_ordinal_number(n)

This function returns the buffer for the ordinal number specified by parameter n or -1 if no buffer is found.

lightline#bufferline#go(n)

This function switches to the buffer with the ordinal number specified by parameter n. To switch to the first buffer using a mapping you can use the function like this:

nmap <Leader>1 :call lightline#bufferline#go(1)<CR>

lightline#bufferline#delete(n)

This function deletes the buffer with the ordinal number specified by parameter n. To delete the first buffer using a mapping you can use the function like this:

nmap <D-1> :call lightline#bufferline#delete(1)<CR>

Example

The following minimal example adds the bufferline to the lightline tabline and demonstrates a few custom bufferline options:

let g:lightline#bufferline#show_number  = 1
let g:lightline#bufferline#shorten_path = 0
let g:lightline#bufferline#unnamed      = '[No Name]'

let g:lightline                  = {}
let g:lightline.tabline          = {'left': [['buffers']], 'right': [['close']]}
let g:lightline.component_expand = {'buffers': 'lightline#bufferline#buffers'}
let g:lightline.component_type   = {'buffers': 'tabsel'}

FAQ

Q: I can't see the tabline!
A: Add set showtabline=2 to your configuration. This forces the tabline to always show.

Q: My vim GUI (MacVim, gVim, etc.) displays a graphical tabline and not the lightline tabline!
A: Add set guioptions-=e to your configuration (and guard it with if has('gui_running') ... endif). This will disable the GUI tabline and enable the lightline tabline.

Q: How can I hide the path and show only the filename?
A: Add let g:lightline#bufferline#filename_modifier = ':t' to your configuration.

License

Released under the MIT License