Description
I've been diving into telescope recently, as I've been using it for some time but never configured it thoroughly. I read the entire :h manual inside Neovim.
I hard a hard time understanding what options the individual pickers or extensions passed into setup() could take. It took me a while to understand that a picker's config table accepts the same keys as "defaults" table plus its own config keys which are shown in telescope.builtin. Writing it down I understand that it's kinda implied that defaults can be overriden, but it took me some time to fully get how it works.
Do you think this warrants a little clarification ?
In my humble opinion, it'd be worth modifying the telescope.setup section and the telescope.builtin section, here is my opinion on the parts the documentation is lacking clarity, as well as my humble proposal. I'd love to hear your feedbacks on this.
:h telescope.setup()
telescope.setup({opts}) *telescope.setup()*
Setup function to be run by user. Configures the defaults, pickers and
extensions of telescope.
Usage:
>
require('telescope').setup{
defaults = {
-- Default configuration for telescope goes here:
-- config_key = value,
-- ..
},
pickers = {
-- Default configuration for builtin pickers goes here:
-- picker_name = {
-- picker_config_key = value,
-- ...
-- }
-- ADD: Each picker table accepts the same opts as the defaults table.
-- ADD: On top of those, the pickers each have additional opts, which
-- ADD: you can learn about in telescope.builtin.
-- ADD: Options set here will be applied every time you call this builtin picker
-- DEL: Now the picker_config_key will be applied every time you call this
-- DEL: builtin picker
},
extensions = {
-- Your extension configuration goes here:
-- extension_name = {
-- extension_config_key = value,
-- }
-- ADD: Just like builtin pickers, extension can take the same opts as the
-- ADD: the defaults table in order to override them.
-- please take a look at the readme of the extension you want to configure
}
}
Valid keys for {opts.defaults}
ADD: (Those keys are also valid for builtin pickers and extensions)
-- And then the list of opts possible keysI have to note that the builtin part of the builtin help kinda implies this but it doesn't state it clearly. What I struggled to understand is that the builtin pickers options extend the default ones. Maybe this section could be clarified?
:h telescope.builtin
To use any of Telescope's default options or any picker-specific options, call
your desired picker by passing a lua table to the picker with all of the
options you want to use. Here's an example with the live_grep picker:
>
:lua require('telescope.builtin').live_grep({
prompt_title = 'find string in open buffers...',
grep_open_files = true
})
-- or with dropdown theme
:lua require('telescope.builtin').find_files(require('telescope.themes').get_dropdown{
previewer = false
})Neovim version
NVIM v0.10.1
Build type: Release
LuaJIT 2.1.1713484068
Operating system and version
Debian 12
Telescope version / branch / rev
0.1.X
checkhealth telescope
telescope: health#telescope#check
Checking for required plugins ~
- OK plenary installed.
- OK nvim-treesitter installed.
Checking external dependencies ~
- OK rg: found ripgrep 14.1.0 (rev 47797d5476)
- WARNING fd: not found. Install [sharkdp/fd](https://github.com/sharkdp/fd) for extended capabilities
===== Installed extensions ===== ~
Telescope Extension: `conflicts` ~
- No healthcheck provided
Telescope Extension: `dap` ~
- No healthcheck provided
Telescope Extension: `luasnip` ~
- No healthcheck provided
Telescope Extension: `ui-select` ~
- No healthcheck provided
Steps to reproduce
- :h telescope
Expected behavior
No response
Actual behavior
See desc
Minimal config
local root = vim.fn.fnamemodify("./.repro", ":p")
-- set stdpaths to use .repro
for _, name in ipairs { "config", "data", "state", "cache" } do
vim.env[("XDG_%s_HOME"):format(name:upper())] = root .. "/" .. name
end
-- bootstrap lazy
local lazypath = root .. "/plugins/lazy.nvim"
if not vim.uv.fs_stat(lazypath) then
vim.fn.system {
"git",
"clone",
"--filter=blob:none",
"https://github.com/folke/lazy.nvim.git",
lazypath,
}
end
vim.opt.runtimepath:prepend(lazypath)
-- install plugins
local plugins = {
{
"nvim-telescope/telescope.nvim",
dependencies = {
"nvim-lua/plenary.nvim",
},
config = function()
-- ADD INIT.LUA SETTINGS THAT ARE _NECESSARY_ FOR REPRODUCING THE ISSUE
require("telescope").setup {}
end,
},
}
require("lazy").setup(plugins, {
root = root .. "/plugins",
})
Description
I've been diving into telescope recently, as I've been using it for some time but never configured it thoroughly. I read the entire :h manual inside Neovim.
I hard a hard time understanding what options the individual pickers or extensions passed into setup() could take. It took me a while to understand that a picker's config table accepts the same keys as "defaults" table plus its own config keys which are shown in telescope.builtin. Writing it down I understand that it's kinda implied that defaults can be overriden, but it took me some time to fully get how it works.
Do you think this warrants a little clarification ?
In my humble opinion, it'd be worth modifying the telescope.setup section and the telescope.builtin section, here is my opinion on the parts the documentation is lacking clarity, as well as my humble proposal. I'd love to hear your feedbacks on this.
:h telescope.setup()
telescope.setup({opts}) *telescope.setup()* Setup function to be run by user. Configures the defaults, pickers and extensions of telescope. Usage: > require('telescope').setup{ defaults = { -- Default configuration for telescope goes here: -- config_key = value, -- .. }, pickers = { -- Default configuration for builtin pickers goes here: -- picker_name = { -- picker_config_key = value, -- ... -- } -- ADD: Each picker table accepts the same opts as the defaults table. -- ADD: On top of those, the pickers each have additional opts, which -- ADD: you can learn about in telescope.builtin. -- ADD: Options set here will be applied every time you call this builtin picker -- DEL: Now the picker_config_key will be applied every time you call this -- DEL: builtin picker }, extensions = { -- Your extension configuration goes here: -- extension_name = { -- extension_config_key = value, -- } -- ADD: Just like builtin pickers, extension can take the same opts as the -- ADD: the defaults table in order to override them. -- please take a look at the readme of the extension you want to configure } } Valid keys for {opts.defaults} ADD: (Those keys are also valid for builtin pickers and extensions) -- And then the list of opts possible keysI have to note that the builtin part of the builtin help kinda implies this but it doesn't state it clearly. What I struggled to understand is that the builtin pickers options extend the default ones. Maybe this section could be clarified?
:h telescope.builtin
Neovim version
Operating system and version
Debian 12
Telescope version / branch / rev
0.1.X
checkhealth telescope
Steps to reproduce
Expected behavior
No response
Actual behavior
See desc
Minimal config