leigh/telescope.nvim
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ab30ed8ef65f13b223c5149019b15ae49993f32b
telescope.nvim/README.md
tami5 ab30ed8ef6 Complete rewrite of README (#216) 
Many thanks tami5

- New structure:
  - Getting Started
  - Customization
  - Built-in pickers
  - API
  - Media
  - Gallery
  - FAQ
  - Contributing

Co-authored-by: Patrick Lambein <patrick@lambein.name>
2020-11-17 09:56:05 +01:00

578 lines
24 KiB
Markdown
Raw Blame History

# Telescope.nvim
> **Telescope**
> An arrangement of lenses or mirrors or both that gathers light,
> permitting direct observation or photographic recording of distant objects.
>
> — thefreedictionary
![](https://raw.githubusercontent.com/tjdevries/media.repo/master/telescope.nvim/simple_rg_v1.gif)
`Telescope.nvim` is a next generation library for creating floating pickers
with advanced features. It is written in `lua` and is built on top of latest
awesome features from `neovim` core. `Telescope.nvim` is centered around
modularity *to the extent that* the pickers can be customized in isolation from
one another (such presentation, algorithm, mappings ... etc).
In addition to extensions which can be found
[here](https://github.com/nvim-telescope)`, Telescope.nvim` comes with a
growing number of community driven [built-in pickers](#built-in-pickers),
covering a wide range of use cases and tools, and offers a customizable user
interface.
<!-- You can read this documentation from start to finish, or you can look at the -->
<!-- outline and directly jump to the section that interests you most. -->
- [Getting Started](#getting-started)
- [Customization](#customization)
- [Built-in pickers](#built-in-pickers)
- [API](#api)
- [Media](#media)
- [Gallery](https://github.com/nvim-telescope/telescope.nvim/wiki/Gallery)
- [FAQ](#faq)
- [Contributing](#contribution)
## Getting Started
This section should guide to run your first built-in pickers :smile:
[Neovim Nightly (0.5)](https://github.com/neovim/neovim/releases/tag/nightly)
is required for `telescope.nvim` to work.
#### Optional dependences
- [sharkdp/bat](https://github.com/sharkdp/bat) (preview)
- [sharkdp/fd](https://github.com/sharkdp/fd) (finder)
- [BurntSushi/ripgrep](https://github.com/BurntSushi/ripgrep) (finder)
- [nvim-treesitter/nvim-treesitter](https://github.com/nvim-treesitter/nvim-treesitter) (finder/preview)
- [neovim LSP]( https://neovim.io/doc/user/lsp.html) (picker)
- [devicons](https://github.com/kyazdani42/nvim-web-devicons) (icons)
#### Installation
Using [vim-plug](https://github.com/junegunn/vim-plug)
```viml
Plug 'nvim-lua/popup.nvim'
Plug 'nvim-lua/plenary.nvim'
Plug 'nvim-telescope/telescope.nvim'
```
Using [dein](https://github.com/Shougo/dein.vim)
```viml
call dein#add('nvim-lua/popup.nvim')
call dein#add('nvim-lua/plenary.nvim')
call dein#add('nvim-telescope/telescope.nvim')
```
Using [packer.nvim](https://github.com/wbthomason/packer.nvim)
```lua
use {
'nvim-telescope/telescope.nvim',
requires = {{'nvim-lua/popup.nvim'}, {'nvim-lua/plenary.nvim'}}
}
```
#### Usage
Try the command `:Telescope find_files<cr>`
to see if `telescope.nvim` is installed correctly.
```viml
" Find files using Telescope command-line sugar.
nnoremap <leader>ff <cmd>Telescope find_files<cr>
nnoremap <leader>fg <cmd>Telescope live_grep<cr>
nnoremap <leader>fb <cmd>Telescope buffers<cr>
nnoremap <leader>fh <cmd>Telescope help_tags<cr>
" Using lua functions
nnoremap <leader>ff <cmd>lua require('telescope.builtin').find_files()<cr>
nnoremap <leader>fg <cmd>lua require('telescope.builtin').live_grep()<cr>
nnoremap <leader>fb <cmd>lua require('telescope.builtin').buffers()<cr>
nnoremap <leader>ff <cmd>lua require('telescope.builtin').help_tags()<cr>
```
See [built-in pickers](#built-in-pickers) for the list of all built-in
functions.
## Customization
This section should help you explore available options to configure and
customize your `telescope.nvim`.
`Telescope.nvim` can be configured at two levels:
- **Global** (i.e. affecting all pickers) through the `setup()` method, or
- **Individual** (i.e. affecting a single picker) through passing `opts` built-in pickers (e.g. `builtin.fd(opts)` )
see [Configuration recipes](https://github.com/nvim-telescope/telescope.nvim/wiki/Configuration-Recipes) wiki page for idea.
#### Telescope Defaults
As an example of using the `setup()` method, the following code configures
`telescope.nvim` to its default settings.
```lua
require('telescope').setup{
defaults = {
vimgrep_arguments = {
'rg',
'--color=never',
'--no-heading',
'--with-filename',
'--line-number',
'--column',
'--smart-case'
},
prompt_position = "bottom",
prompt_prefix = ">",
selection_strategy = "reset",
sorting_strategy = "descending",
layout_strategy = "horizontal",
layout_defaults = {
-- TODO add builtin options.
},
file_sorter = require'telescope.sorters'.get_fuzzy_file ,
file_ignore_patterns = {},
generic_sorter = require'telescope.sorters'.get_generic_fuzzy_sorter,
shorten_path = true,
winblend = 0,
width = 0.75,
preview_cutoff = 120,
results_height = 1,
results_width = 0.8,
border = {},
borderchars = { '─', '│', '─', '│', '╭', '╮', '╯', '╰'},
color_devicons = true,
use_less = true,
}
}
```
To embed the above code snippet in a `.vim` file
(for example in `after/plugin/telescope.nvim.vim`),
wrap it in `lua << EOF code-snippet EOF`:
```lua
lua << EOF
require('telescope').setup{
-- ...
}
EOF
```
<!-- TODO: move some options to Options affecting Behaviour -->
#### Options affecting Presentation
| Keys | Description | Options |
|------------------------|-------------------------------------------------------|----------------------------|
| `prompt_position` | Where the prompt should be located. | top/bottom |
| `prompt_prefix` | What should the prompt prefix be. | string |
| `sorting_strategy` | Where first selection should be located. | descending/ascending |
| `layout_strategy` | How the telescope is drawn. | [supported layouts](https://github.com/nvim-telescope/telescope.nvim/wiki/Layouts) |
| `winblend` | How transparent is the telescope window should be. | NUM |
| `layout_defaults` | Layout specific configuration ........ TODO | TODO |
| `width` | TODO | NUM |
| `preview_cutoff` | TODO | NUM |
| `results_height` | TODO | NUM |
| `results_width` | TODO | NUM |
| `borderchars` | The border chars, it gives border telescope window | dict |
| `color_devicons` | Whether to color devicons or not | boolean |
| `use_less` | Whether to use less of cat/bat | boolean |
| `scroll_strategy` | How to behave when the when there are no more item next/prev | cycle, nil |
#### Options affecting Sorting
| Keys | Description | Options |
|------------------------|-------------------------------------------------------|----------------------------|
| `file_sorter` | The sorter for file lists. | [Sorters](#built-in-sorters) |
| `generic_sorter` | The sorter for everything else. | [Sorters](#built-in-sorters) |
| `vimgrep_arguments` | The command line argument for grep search ... TODO. | dict |
| `selection_strategy` | What happens to the selection if the list changes. | follow/reset/row |
| `file_ignore_patterns` | Pattern to be ignored `{ "scratch/.*", "%.env"}` | dict |
| `shorten_path` | Whether to shorten paths or not. | boolean |
#### Mappings
Mappings are fully customizable.
Many familiar mapping patterns are setup as defaults.
| Mappings | Action |
|----------------|----------------------------------|
| `<C-n>/<Down>` | Next item |
| `<C-p>/<Up>` | Previous item |
| `j/k` | Next/previous (in normal mode) |
| `<CR>` | Confirm selection |
| `<C-x>` | go to file selection as a split |
| `<C-v>` | go to file selection as a vsplit |
| `<C-t>` | go to a file in a new tab |
| `<C-u>` | scroll up in preview window |
| `<C-d>` | scroll down in preview window |
| `<C-c>` | close telescope |
| `<Esc>` | close telescope (in normal mode) |
To see the full list of mappings, check out `lua/telescope/mappings.lua` and
the `default_mappings` table.
Much like [built-in pickers](#built-in-pickers), there are a number of
[built-in actions](https://github.com/nvim-telescope/telescope.nvim/blob/master/lua/telescope/actions/init.lua) you can pick from to remap your telescope buffer mappings or create a new custom action:
<!-- TODO: add custom action in addition to a function that gets ran after a given action--->
```lua
-- Built-in actions
local transform_mod = require('telescope.actions.mt').transform_mod
-- or create your custom action
local my_cool_custom_action = transform_mod({
x = function()
print("This function ran after another action. Prompt_bufnr: " .. prompt_bufnr)
-- Enter your function logic here. You can take inspiration from lua/telescope/actions.lua
end,
})
```
To remap telescope mappings and make them apply to all pickers:
```lua
local actions = require('telescope.actions')
-- Global remapping
------------------------------
require('telescope').setup{
defaults = {
mappings = {
i = {
-- To disable a keymap, put [map] = false
-- So, to not map "<C-n>", just put
["<c-x>"] = false,
-- Otherwise, just set the mapping to the function that you want it to be.
["<C-i>"] = actions.goto_file_selection_split,
-- Add up multiple actions
["<CR>"] = actions.goto_file_selection_edit + actions.center,
-- You can perform as many actions in a row as you like
["<CR>"] = actions.goto_file_selection_edit + actions.center + my_cool_custom_action,
},
n = {
["<esc>"] = actions.close
["<C-i>"] = my_cool_custom_action,
},
},
}
}
```
For a [picker](#built-in-pickers) specific remapping, it can be done by setting
its `attach_mappings` key to a function, like this
```lua
local actions = require('telescope.actions')
-- Picker specific remapping
------------------------------
require('telescope.builtin').fd({ -- or new custom picker's attach_mappings field:
attach_mappings = function(prompt_bufnr)
-- This will replace goto_file_selection_edit no mather on which key it is mapped by default
actions.goto_file_selection_edit:replace(function()
local entry = actions.get_selected_entry()
actions.close(prompt_bufnr)
print(vim.inspect(entry))
-- Code here
end)
-- You can also enhance an action with pre and post action which will run before of after an action
actions.goto_file_selection_split:enhance ({
pre = function()
-- Will run before actions.goto_file_selection_split
end,
post = function()
-- Will run after actions.goto_file_selection_split
end,
})
-- Or replace for all commands: edit, new, vnew and tab
actions._goto_file_selection:replace(function(_, cmd)
print(cmd) -- Will print edit, new, vnew or tab depending on your keystroke
end)
return true
end,
})
```
<!-- TODO: Move to wiki page made specifically for creating pickers -->
<!-- To override a action, you have to use `attach_mappings` like this (prefered method): -->
<!-- ```lua -->
<!-- function my_custom_picker(results) -->
<!-- pickers.new(opts, { -->
<!-- prompt_title = 'Custom Picker', -->
<!-- finder = finders.new_table(results), -->
<!-- sorter = sorters.fuzzy_with_index_bias(), -->
<!-- attach_mappings = function(prompt_bufnr) -->
<!-- -- This will replace goto_file_selection_edit no mather on which key it is mapped by default -->
<!-- actions.goto_file_selection_edit:replace(function() -->
<!-- -- Code here -->
<!-- end) -->
<!-- -- You can also enhance an action with post and post action which will run before of after an action -->
<!-- actions.goto_file_selection_split:enhance { -->
<!-- pre = function() -->
<!-- -- Will run before actions.goto_file_selection_split -->
<!-- end, -->
<!-- post = function() -->
<!-- -- Will run after actions.goto_file_selection_split -->
<!-- end, -->
<!-- } -->
<!-- -- Or replace for all commands: edit, new, vnew and tab -->
<!-- actions._goto_file_selection:replace(function(_, cmd) -->
<!-- print(cmd) -- Will print edit, new, vnew or tab depending on your keystroke -->
<!-- end) -->
<!-- return true -->
<!-- end, -->
<!-- }):find() -->
<!-- end -->
<!-- ``` -->
<!-- See `lua/telescope/builtin.lua` for examples on how to `attach_mappings` in the prefered way. -->
## Built-in Pickers
Built-in function ready to be bound to any key you like :smile:.
| Functions | Description |
|-------------------------------------|------------------------------------------------------------------|
| `builtin.planets` | Demo showcasing how simple to create pickers with telescope. |
| `builtin.builtin` | Lists Built-in pickers and run them on enter. |
| `builtin.find_files` | Lists Files in current directory. |
| `builtin.git_files` | Lists Git files in current directory. |
| `builtin.buffers` | Lists Open buffers in the current vim instance. |
| `builtin.oldfiles` | Lists Previously open files. |
| `builtin.commands` | Lists Available plugin/user commands and run it. |
| `builtin.tags` | Lists Tags in current directory with preview (ctags -R) |
| `builtin.command_history` | Lists Commands previously ran and run it on enter. |
| `builtin.help_tags` | Lists Available help tags and open help document |
| `builtin.man_pages` | Lists Man entries. |
| `builtin.marks` | Lists Markers and their value. |
| `builtin.colorscheme` | Lists Colorscheme and switch to it on enter. |
| `builtin.treesitter` | Lists Function names, variables, from Treesitter! |
| `builtin.live_grep` | Searches in current directory files (respecting .gitignore) |
| `builtin.current_buffer_fuzzy_find` | Searches in current buffer lines. |
| `builtin.current_buffer_tags` | Lists Tags in current buffer |
| `builtin.grep_string` | Searches for a string under the cursor in current directory. |
| `builtin.lsp_references` | Searches in LSP references. |
| `builtin.lsp_document_symbols` | Searches in LSP Document Symbols in the current document. |
| `builtin.lsp_workspace_symbols` | Searches in LSP all workspace symbols. |
| `builtin.lsp_code_actions` | Lists LSP action to be trigged on enter |
| `builtin.quickfix` | Lists items from quickfix |
| `builtin.loclist` | Lists items from current window's location list. |
| `builtin.reloader` | Lists lua modules and reload them on enter |
| `builtin.vim_options` | Lists vim options and on enter edit the options value |
| `builtin.keymaps` | Lists normal-mode mappings |
| `builtin.git_commits` | Lists git commits with diff preview and on enter checkout the commit.|
| `builtin.git_bcommits` | Lists buffer's git commits with diff preview and
checkouts it out on enter|
| `builtin.git_branches` | Lists all branches with log preview and checkout action |
| `builtin.git_status` | Lists current changes per file with diff preview and add action. (Multiselection still WIP) |
| .................................. | Your next awesome finder function here :D |
#### Built-in Sorters
| Sorters | Description |
|------------------------------------|-----------------------------------------------------------------|
| `sorters.get_fuzzy_file` | Telescope's default sorter for files |
| `sorters.get_generic_fuzzy_sorter` | Telescope's default sorter for everything else |
| `sorters.get_levenshtein_sorter` | Using Levenshtein distance algorithm (don't use :D) |
| `sorters.get_fzy_sorter` | Using fzy algorithm |
| `sorters.fuzzy_with_index_bias` | Used to list stuff with consideration to when the item is added |
| .................................. | Your next awesome sorter here :D |
A `Sorter` is called by the `Picker` on each item returned by the `Finder`. It
return a number, which is equivalent to the "distance" between the current
`prompt` and the `entry` returned by a `finder`.
<!-- TODO review -->
<!-- - Currently, it's not possible to delay calling the `Sorter` until the end of the execution, it is called on each item as we receive them. -->
<!-- - This was done this way so that long running / expensive searches can be instantly searchable and we don't have to wait til it completes for things to start being worked on. -->
<!-- - However, this prevents using some tools, like FZF easily. -->
<!-- - In the future, I'll probably add a mode where you can delay the sorting til the end, so you can use more traditional sorting tools. -->
## Built-in Themes
Common groups of settings can be set up to allow for themes.
We have some built in themes but are looking for more cool options.
| Themes | Description |
|--------------------------|-----------------------------------------------------------------------|
| `themes.get_dropdown` | A list like centered list. [example](https://i.imgur.com/SorAcXv.png) |
| ... | Your next awesome theme here :D |
To use a theme, simply append it to a built-in function:
```vim
nnoremap <Leader>f :lua require'telescope.builtin'.find_files(require('telescope.themes').get_dropdown({}))<cr>
" Change an option
nnoremap <Leader>f :lua require'telescope.builtin'.find_files(require('telescope.themes').get_dropdown({ winblend = 10 }))<cr>
```
Themes should work with every `telescope.builtin` function. If you wish to
make theme, check out `lua/telescope/themes.lua`. If you need more features,
make an issue :).
## API
<!-- TODO: need to provide working examples for every api -->
#### Finders
<!-- TODO what is finders -->
```lua
-- lua/telescope/finders.lua
Finder:new{
entry_maker = function(line) end,
fn_command = function() { command = "", args = { "ls-files" } } end,
static = false,
maximum_results = false
}
```
#### Picker
<!-- TODO: this section need some love, an in-depth explanation will be appreciated it need some in depth explanation -->
<!-- TODO what is pickers -->
This section is an overview of how custom pickers can be created any configured.
```lua
-- lua/telescope/pickers.lua
Picker:new{
prompt_title = "", -- REQUIRED
finder = FUNCTION, -- see lua/telescope/finder.lua
sorter = FUNCTION, -- see lua/telescope/sorter.lua
previewer = FUNCTION, -- see lua/telescope/previewer.lua
selection_strategy = "reset", -- follow, reset, row
border = {},
borderchars = {"─", "│", "─", "│", "┌", "┐", "┘", "└"},
preview_cutoff = 120,
}
```
To override only *some* of the default mappings, you can use the
`attach_mappings` key in the `setup` table. For example:
```lua
function my_custom_picker(results)
pickers.new(opts, {
prompt_title = 'Custom Picker',
finder = finders.new_table(results),
sorter = sorters.fuzzy_with_index_bias(),
attach_mappings = function(_, map)
-- Map "<CR>" in insert mode to the funciton, actions.set_command_line
map('i', '<CR>', actions.set_command_line)
return true
end,
}):find()
end
```
#### Layout (display)
<!-- TODO need some work -->
`Resolvable`:
1. 0 <= number < 1:
- This means total height as a percentage
2. 1 <= number:
- This means total height as a fixed number
3. function(picker, columns, lines):
- returns one of the above options
- `return max.min(110, max_rows * .5)`
```lua
layout_strategies.horizontal = function(self, max_columns, max_lines)
local layout_config = validate_layout_config(self.layout_config or {}, {
width_padding = "How many cells to pad the width",
height_padding = "How many cells to pad the height",
preview_width = "(Resolvable): Determine preview width",
})
...
end
```
#### Command-line
All `telescope.nvim` functions are wrapped in `vim` commands for easy access, its
supports tab completions and settings options.
```viml
" Tab completion
:Telescope |<tab>
:Telescope find_files
" Setting options
:Telescope find_files prompt_prefix=🔍
" If option is table type in lua code ,you can use `,` connect each command string eg:
" find_command,vimgrep_arguments they are both table type. so config it in commandline like
:Telecope find_files find_command=rg,--ignore,--hidden,--files prompt_prefix=🔍
```
## Media
- [What is Telescope? (Video)](https://www.twitch.tv/teej_dv/clip/RichDistinctPlumberPastaThat)
- [More advanced configuration (Video)](https://www.twitch.tv/videos/756229115)
- [Example video](https://www.youtube.com/watch?v=65AVwHZflsU)
## FAQ
<!-- Any question answered in issues should be written here -->
### How to change some defaults in built-in functions?
All options available from the setup function (see [Configuration options]()) and
some other functions can be easily changed in custom pickers or built-in
functions.
<!-- TODO: insert a list of available options like previewer and prompt prefix -->
```lua
-- Disable preview for find files
nnoremap <leader>ff :lua require('telescope.builtin').find_files({previewer = false})<CR>
-- Change change prompt prefix for find_files builtin function:
nnoremap <leader>fg :lua require('telescope.builtin').live_grep({ prompt_prefix=🔍 })<CR>
nnoremap <leader>fg :Telescope live_grep prompt_prefix=🔍<CR>
```
### How to change Telescope Highlights group?
There are 10 highlights group you can play around with in order to meet your needs:
```viml
highlight TelescopeSelection guifg=#D79921 gui=bold " selected item
highlight TelescopeSelectionCaret guifg=#CC241D " selection caret
highlight TelescopeMultiSelection guifg=#928374 " multisections
highlight TelescopeNormal guibg=#00000 " floating windows created by telescope.
" Border highlight groups.
highlight TelescopeBorder guifg=#ffffff
highlight TelescopePromptBorder guifg=#ffffff
highlight TelescopeResultsBorder guifg=#ffffff
highlight TelescopePreviewBorder guifg=#ffffff
" Used for highlighting characters that you match.
highlight TelescopeMatching guifg=blue
" Used for the prompt prefix
highlight TelescopePromptPrefix guifg=red
```
To checkout the default values of the highlight groups, checkout `plugin/telescope.vim`
### How to add autocmds to telescope prompt ?
`TelescopePrompt` is the prompt Filetype. You can customize the Filetype as you would normally.
## Contributing
All contributions are welcome! Just open a pull request.
<!-- TODO: add plugin documentation -->
When approved,
changes in the user interface and new built-in functions
will need to be reflected in the documentation and in `README.md`.
Reference in New Issue View Git Blame Copy Permalink