README.md

telescope-tabs

Fly through your tabs in neovim ✈️

Important Note

If you don't want to use telescope, there's also a version using vim.ui.select instead of telescope. Checkout the vim_ui_select branch :)

Usage

You can show the picker from neovim's cmd-line by executing

:Telescope telescope-tabs list_tabs

Or straight from the plugin's path with lua

:lua require('telescope-tabs').list_tabs()

You can press C-d (insert mode) or D (normal mode) on any Item in the picker to close the tab (respectively all windows in it). To change the keybinding, look at configure.

But telescope-tabs does not only provide a picker! You can also call

:lua require('telescope-tabs').go_to_previous()

to switch to the last opened tab immediately. This does not only work when switching tabs with this extension, but also when you use Neovims builtin tab movement methods.

This plugin improves upon the already present g<Tab> shortcut by keeping track of a "last shown tab stack". Consequently, if you close the most previously visited tab, g<Tab> will fail. However, telescope-tabs will happily show the second last tab.

I would recommend to bind this to a shortcut if you wanna use this regularly :^)

Installation

Install with your favorite Neovim package manager.

Example with lazy.nvim:

{
	'LukasPietzschmann/telescope-tabs',
	config = function()
		require('telescope').load_extension 'telescope-tabs'
		require('telescope-tabs').setup {
			-- Your custom config :^)
		}
	end,
	dependencies = { 'nvim-telescope/telescope.nvim' },
}

Example with packer.nvim:

use {
	'LukasPietzschmann/telescope-tabs',
	requires = { 'nvim-telescope/telescope.nvim' },
	config = function()
		require'telescope-tabs'.setup{
			-- Your custom config :^)
		}
	end
}

Configure

Different configurations can be seen in the configs wiki. Feel free to add your own!

If you want to come up with your own config, these are the settings you can tweak:

entry_formatter

This changes how a tab is represented in the picker. By default the following function is used:

entry_formatter = function(tab_id, buffer_ids, file_names, file_paths, is_current)
	local entry_string = table.concat(file_names, ', ')
	return string.format('%d: %s%s', tab_id, entry_string, is_current and ' <' or '')
end,

To alter this behaviour, just assign your own function.

entry_ordinal

This changes how tabs are sorted in the picker. The ordinal is also used to determine which entries match a given search query. The following function is used by default:

entry_ordinal = function(tab_id, buffer_ids, file_names, file_paths, is_current)
	return table.concat(file_names, ' ')
end,

show_preview

This controls whether a preview is shown or not. The default is true:

show_preview = true,

close_tab_shortcut

These shortcuts allow you to close a selected tabs right from the picker. The defaults are...

close_tab_shortcut_i = '<C-d>', -- if you're in insert mode
close_tab_shortcut_n = 'D',     -- if you're in normal mode

Note, that their value do not get parsed or checked, so they should follow the regular format for keybindings.

Documentation

See telescope-tabs.txt.