barbar.nvim

To restore buffer order and pinning status, ensure sessionoptions contains globals and the User SessionSavePre event is triggered before saving the session.

mini.sessions

vim.opt.sessionoptions:append 'globals'
require'mini.sessions'.setup {
  hooks = {
    pre = {
      write = function() vim.api.nvim_exec_autocmds('User', {pattern = 'SessionSavePre'}) end,
    },
  },
}

persistence.nvim

require'persistence'.setup {
  options = {--[[<other options>,], 'globals'},
  pre_save = function() vim.api.nvim_exec_autocmds('User', {pattern = 'SessionSavePre'}) end,
}

persisted.nvim

vim.opt.sessionoptions:append 'globals'
vim.api.nvim_create_autocmd({ 'User' }, {
  pattern = 'PersistedSavePre',
  group = vim.api.nvim_create_augroup('PersistedHooks', {}),
  callback = function()
    vim.api.nvim_exec_autocmds('User', { pattern = 'SessionSavePre' })
  end,
})

resession.nvim

Add the barbar extension to your resession config. If using lazy.nvim, ensure barbar.nvim is a dependency of resession so the extension loads first.

extensions = {
  barbar = {},
}

Custom Implementation

Use this command to wrap :mksession with the necessary SessionSavePre event:

vim.opt.sessionoptions:append 'globals'
vim.api.nvim_create_user_command(
  'Mksession',
  function(attr)
    vim.api.nvim_exec_autocmds('User', {pattern = 'SessionSavePre'})

    -- Neovim 0.8+
    vim.cmd.mksession {bang = attr.bang, args = attr.fargs}

    -- Neovim 0.7
    vim.api.nvim_command('mksession ' .. (attr.bang and '!' or '') .. ' ' .. attr.args)
  end,
  {bang = true, complete = 'file', desc = 'Save barbar with :mksession', nargs = '?'}
)

Barbar does not provide default keybindings. You must map commands to your preferred keys. Below are common mapping patterns for moving between buffers, re-ordering them, jumping to specific positions, pinning, and closing buffers.

Note for Mac users: If using iTerm, ensure your Option key is mapped to Esc+ to use Alt (<A-...>) mappings correctly.

local map = vim.api.nvim_set_keymap
local opts = { noremap = true, silent = true }

-- Move to previous/next
map('n', '<A-,>', '<Cmd>BufferPrevious<CR>', opts)
map('n', '<A-.>', '<Cmd>BufferNext<CR>', opts)

-- Re-order to previous/next
map('n', '<A-<>', '<Cmd>BufferMovePrevious<CR>', opts)
map('n', '<A->>', '<Cmd>BufferMoveNext<CR>', opts)

-- Goto buffer in position...
map('n', '<A-1>', '<Cmd>BufferGoto 1<CR>', opts)
map('n', '<A-2>', '<Cmd>BufferGoto 2<CR>', opts)
map('n', '<A-3>', '<Cmd>BufferGoto 3<CR>', opts)
map('n', '<A-4>', '<Cmd>BufferGoto 4<CR>', opts)
map('n', '<A-5>', '<Cmd>BufferGoto 5<CR>', opts)
map('n', '<A-6>', '<Cmd>BufferGoto 6<CR>', opts)
map('n', '<A-7>', '<Cmd>BufferGoto 7<CR>', opts)
map('n', '<A-8>', '<Cmd>BufferGoto 8<CR>', opts)
map('n', '<A-9>', '<Cmd>BufferGoto 9<CR>', opts)
map('n', '<A-0>', '<Cmd>BufferLast<CR>', opts)

-- Pin/unpin buffer
map('n', '<A-p>', '<Cmd>BufferPin<CR>', opts)

-- Close buffer
map('n', '<A-c>', '<Cmd>BufferClose<CR>', opts)

-- Magic buffer-picking mode
map('n', '<C-p>',   '<Cmd>BufferPick<CR>', opts)
map('n', '<C-s-p>', '<Cmd>BufferPickDelete<CR>', opts)

-- Sort automatically by...
map('n', '<Space>bb', '<Cmd>BufferOrderByBufferNumber<CR>', opts)
map('n', '<Space>bn', '<Cmd>BufferOrderByName<CR>', opts)
map('n', '<Space>bd', '<Cmd>BufferOrderByDirectory<CR>', opts)
map('n', '<Space>bl', '<Cmd>BufferOrderByLanguage<CR>', opts)
map('n', '<Space>bw', '<Cmd>BufferOrderByWindowNumber<CR>', opts)

Install barbar.nvim using your preferred plugin manager.

Requirements:

• Neovim v0.7+

Optional Dependencies:

• nvim-web-devicons: For file icons (requires a Nerd Font by default).
• gitsigns.nvim: For git status integration.

Note: If using lazy.nvim, it is recommended to set vim.g.barbar_auto_setup = false in the init function to manage setup manually via opts.

require('lazy').setup {
  {'romgrk/barbar.nvim',
    dependencies = {
      'lewis6991/gitsigns.nvim', -- OPTIONAL: for git status
      'nvim-tree/nvim-web-devicons', -- OPTIONAL: for file icons
    },
    init = function() vim.g.barbar_auto_setup = false end,
    opts = {
      -- lazy.nvim will automatically call setup for you. put your options here, anything missing will use the default:
      -- animation = true,
      -- insert_at_start = true,
      -- …etc.
    },
    version = '^1.0.0', -- optional: only update when a new 1.x version is released
  },
}

The following is a reference of available configuration keys for require'barbar'.setup { ... }. Note that defaults are suitable for most users.

{
  animation = true, -- Enable/disable animations
  auto_hide = false, -- Automatically hide the tabline when this many buffers are left
  tabpages = true, -- Enable/disable current/total tabpages indicator
  clickable = true, -- Enables/disables clickable tabs
  exclude_ft = {'javascript'}, -- Excludes buffers from the tabline by filetype
  exclude_name = {'package.json'}, -- Excludes buffers from the tabline by name
  focus_on_close = 'left', -- Buffer to focus when closing current (options: 'left', 'previous', 'right')
  hide = {extensions = true, inactive = true}, -- Hide inactive buffers and file extensions
  highlight_alternate = false, -- Disable highlighting alternate buffers
  highlight_inactive_file_icons = false, -- Disable highlighting file icons in inactive buffers
  highlight_visible = true, -- Enable highlighting visible buffers
  icons = {
    buffer_index = false,
    buffer_number = false,
    button = '',
    diagnostics = {
      [vim.diagnostic.severity.ERROR] = {enabled = true, icon = 'ff'},
      [vim.diagnostic.severity.WARN] = {enabled = false},
      [vim.diagnostic.severity.INFO] = {enabled = false},
      [vim.diagnostic.severity.HINT] = {enabled = true},
    },
    gitsigns = {
      added = {enabled = true, icon = '+'},
      changed = {enabled = true, icon = '~'},
      deleted = {enabled = true, icon = '-'},
    },
    filetype = {
      custom_colors = false,
      enabled = true,
    },
    separator = {left = '▎', right = ''},
    separator_at_end = true,
    modified = {button = '●'},
    pinned = {button = '', filename = true},
    preset = 'default', -- 'default', 'powerline', or 'slanted'
    alternate = {filetype = {enabled = false}},
    current = {buffer_index = true},
    inactive = {button = '×'},
    visible = {modified = {buffer_number = false}},
  },
  insert_at_end = false, -- New buffers inserted at end
  insert_at_start = false, -- New buffers inserted at start
  maximum_padding = 1,
  minimum_padding = 1,
  maximum_length = 30,
  minimum_length = 0,
  semantic_letters = true, -- Assign letters for buffer-pick mode based on name
  sidebar_filetypes = {
    NvimTree = true,
    undotree = { text = 'undotree', align = 'center' },
    ['neo-tree'] = {event = 'BufWipeout'},
    Outline = {event = 'BufWinLeave', text = 'symbols-outline', align = 'right'},
  },
  letters = 'asdfjkl;ghnmxcvbziowerutyqpASDFJKLGHNMXCVBZIOWERUTYQP',
  no_name_title = nil, -- Name of unnamed buffers
  sort = {
    ignore_case = true,
  },
}

Highlight groups are constructed using the pattern Buffer<STATUS><PART>.

Statuses:

• Alternate: The :h alternate-file.
• Current: The current buffer.
• Inactive: :h hidden-buffers and :h inactive-buffers.
• Visible: :h active-buffers which are not alternate or current.

Parts:

• ADDED: Git status added.
• Btn: Button for unpinned/unmodified buffers.
• CHANGED: Git status changed.
• DELETED: Git status deleted.
• ERROR: Diagnostic errors.
• HINT: Diagnostic hints.
• Icon: Filetype icon.
• Index: Buffer position in tabline.
• INFO: Diagnostic info.
• Mod: Buffer is modified.
• ModBtn: Button for modified buffers.
• Number: The :h bufnr().
• Pin: Buffer is pinned.
• PinBtn: Button for pinned buffers.
• Sign: Separator between buffers.
• SignRight: Separator between buffers.
• Target: Letter in buffer-pick mode.
• WARN: Diagnostic warnings.

Example: BufferCurrentMod is the current buffer's highlight when modified.

Exceptions:

• BufferOffset: Background of sidebar header.
• BufferScrollArrow: Scroll indicator arrow.
• BufferTabpageFill: Space between buffer list and tabpage.
• BufferTabpages: Tabpages indicator color.
• BufferTabpagesSep: Separator between tabpages count.