leigh/telescope.nvim
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Normalize README, fix typos (#966)

Browse Source
This commit is contained in:
adrian5
2021-07-09 19:11:57 +00:00
committed by GitHub
parent d176dd80da
commit 777ff91ddc
1 changed files with 128 additions and 116 deletions
Download Patch File Download Diff File Expand all files Collapse all files

158
README.md
View File

@@ -1,4 +1,5 @@
# telescope.nvim # telescope.nvim
[![Gitter](https://badges.gitter.im/nvim-telescope/community.svg)](https://gitter.im/nvim-telescope/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge) [![Gitter](https://badges.gitter.im/nvim-telescope/community.svg)](https://gitter.im/nvim-telescope/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
Gaze deeply into unknown regions using the power of the moon. Gaze deeply into unknown regions using the power of the moon.
@@ -6,12 +7,13 @@ Gaze deeply into unknown regions using the power of the moon.
## What Is Telescope? ## What Is Telescope?
`telescope.nvim` is a highly extendable fuzzy finder over lists. Built on the latest `telescope.nvim` is a highly extendable fuzzy finder over lists. Built on the latest
awesome features from `neovim` core. Telescope is centered around awesome features from `neovim` core. Telescope is centered around modularity,
modularity, allowing for easy customization. allowing for easy customization.
Community driven built-in [pickers](#pickers), [sorters](#sorters) and [previewers](#previewers). Community driven built-in [pickers](#pickers), [sorters](#sorters) and [previewers](#previewers).
### Built-in Support: ### Built-in Support:
- [Vim](#vim-pickers) - [Vim](#vim-pickers)
- [Files](#file-pickers) - [Files](#file-pickers)
- [Git](#git-pickers) - [Git](#git-pickers)
@@ -21,11 +23,11 @@ Community driven built-in [pickers](#pickers), [sorters](#sorters) and [previewe
![Preview](https://i.imgur.com/TTTja6t.gif) ![Preview](https://i.imgur.com/TTTja6t.gif)
<sub>For more showcases of Telescope, please visit the [Showcase section](https://github.com/nvim-telescope/telescope.nvim/wiki/Showcase) in the Telescope Wiki</sub> <sub>For more showcases of Telescope, please visit the [Showcase section](https://github.com/nvim-telescope/telescope.nvim/wiki/Showcase) in the Telescope Wiki</sub>
<!-- You can read this documentation from start to finish, or you can look at the --> <!-- 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. --> <!-- outline and directly jump to the section that interests you most. -->
## Telescope Table of Contents ## Telescope Table of Contents
- [Getting Started](#getting-started) - [Getting Started](#getting-started)
- [Usage](#usage) - [Usage](#usage)
- [Customization](#customization) - [Customization](#customization)
@@ -44,12 +46,13 @@ Community driven built-in [pickers](#pickers), [sorters](#sorters) and [previewe
## Getting Started ## Getting Started
This section should guide to run your first built-in pickers :smile:. This section should guide you to run your first built-in pickers :smile:.
[Neovim (v0.5)](https://github.com/neovim/neovim/releases/tag/v0.5.0) or newer [Neovim (v0.5)](https://github.com/neovim/neovim/releases/tag/v0.5.0) or newer
is required for `telescope.nvim` to work. is required for `telescope.nvim` to work.
### Optional dependences ### Optional dependencies
- [sharkdp/bat](https://github.com/sharkdp/bat) (preview) - [sharkdp/bat](https://github.com/sharkdp/bat) (preview)
- [sharkdp/fd](https://github.com/sharkdp/fd) (finder) - [sharkdp/fd](https://github.com/sharkdp/fd) (finder)
- [BurntSushi/ripgrep](https://github.com/BurntSushi/ripgrep) (finder) - [BurntSushi/ripgrep](https://github.com/BurntSushi/ripgrep) (finder)
@@ -96,35 +99,32 @@ nnoremap <leader>fg <cmd>Telescope live_grep<cr>
nnoremap <leader>fb <cmd>Telescope buffers<cr> nnoremap <leader>fb <cmd>Telescope buffers<cr>
nnoremap <leader>fh <cmd>Telescope help_tags<cr> nnoremap <leader>fh <cmd>Telescope help_tags<cr>
" Using lua functions " Using Lua functions
nnoremap <leader>ff <cmd>lua require('telescope.builtin').find_files()<cr> nnoremap <leader>ff <cmd>lua require('telescope.builtin').find_files()<cr>
nnoremap <leader>fg <cmd>lua require('telescope.builtin').live_grep()<cr> nnoremap <leader>fg <cmd>lua require('telescope.builtin').live_grep()<cr>
nnoremap <leader>fb <cmd>lua require('telescope.builtin').buffers()<cr> nnoremap <leader>fb <cmd>lua require('telescope.builtin').buffers()<cr>
nnoremap <leader>fh <cmd>lua require('telescope.builtin').help_tags()<cr> nnoremap <leader>fh <cmd>lua require('telescope.builtin').help_tags()<cr>
``` ```
See [built-in pickers](#pickers) for the list of all built-in See [built-in pickers](#pickers) for a list of all built-in functions.
functions.
## Customization ## Customization
This section should help you explore available options to configure and This section should help you explore available options to configure and
customize your `telescope.nvim`. customize your `telescope.nvim`.
Unlike most vim plugins, `telescope.nvim` can be customized either by applying Unlike most vim plugins, `telescope.nvim` can be customized by either applying
customizations globally or individual per picker. customizations globally, or individually per picker.
- **Global Customization** affecting all pickers can be done through the - **Global Customization** affecting all pickers can be done through the
main `setup()` method (see defaults below) main `setup()` method (see defaults below)
- **Individual Customization** affecting a single picker through passing `opts` - **Individual Customization** affecting a single picker by 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 ideas. built-in pickers (e.g. `builtin.fd(opts)`) see [Configuration recipes](https://github.com/nvim-telescope/telescope.nvim/wiki/Configuration-Recipes) wiki page for ideas.
### Telescope Defaults ### Telescope Defaults
As an example of using the `setup()` method, the following code configures As an example of using the `setup()` method, the following code configures
`telescope.nvim` to its default settings. `telescope.nvim` to its default settings:
```lua ```lua
require('telescope').setup{ require('telescope').setup{
@@ -190,10 +190,10 @@ EOF
### Options affecting Presentation ### Options affecting Presentation
| Keys | Description | Options | | Keys | Description | Options |
|------------------------|-------------------------------------------------------|----------------------------| |------------------------|-------------------------------------------------------|-----------------------------|
| `prompt_prefix` | What should the prompt prefix be. | string | | `prompt_prefix` | What should the prompt prefix be. | string |
| `selection_caret` | What should the selection caret be. | string | | `selection_caret` | What should the selection caret be. | string |
| `entry_prefix` | What should be shown in front of every entry. (current selection excluded) | string| | `entry_prefix` | What should be shown in front of every entry. (current selection excluded) | string |
| `initial_mode` | The initial mode when a prompt is opened. | insert/normal | | `initial_mode` | The initial mode when a prompt is opened. | insert/normal |
| `layout_strategy` | How the telescope is drawn. | [supported layouts](https://github.com/nvim-telescope/telescope.nvim/wiki/Layouts) | | `layout_strategy` | How the telescope is drawn. | [supported layouts](https://github.com/nvim-telescope/telescope.nvim/wiki/Layouts) |
| `layout_config` | Extra settings for fine-tuning how your layout looks | [supported settings](https://github.com/nvim-telescope/telescope.nvim/wiki/Layouts#layout-defaults) | | `layout_config` | Extra settings for fine-tuning how your layout looks | [supported settings](https://github.com/nvim-telescope/telescope.nvim/wiki/Layouts#layout-defaults) |
@@ -211,23 +211,24 @@ EOF
### Options for extension developers ### Options for extension developers
| Keys | Description | Options | | Keys | Description | Options |
|------------------------|-------------------------------------------------------|----------------------------| |--------------------------|-------------------------------------------------------|----------------------------|
| `buffer_previewer_maker` | How a file gets loaded and which highlighter will be used. Extensions will change it | function | | `buffer_previewer_maker` | How a file gets loaded and which highlighter will be used. Extensions will change it | function |
### Options affecting Sorting ### Options affecting Sorting
| Keys | Description | Options | | Keys | Description | Options |
|------------------------|-------------------------------------------------------|----------------------------| |------------------------|-------------------------------------------------------|--------------------------|
| `file_sorter` | The sorter for file lists. | [Sorters](#sorters) | | `file_sorter` | The sorter for file lists. | [Sorters](#sorters) |
| `generic_sorter` | The sorter for everything else. | [Sorters](#sorters) | | `generic_sorter` | The sorter for everything else. | [Sorters](#sorters) |
| `vimgrep_arguments` | The command line argument for grep search ... TODO. | dict | | `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/closest | | `selection_strategy` | What happens to the selection if the list changes. | follow/reset/row/closest |
| `file_ignore_patterns` | Pattern to be ignored `{ "scratch/.*", "%.env" }` | dict | | `file_ignore_patterns` | Pattern to be ignored `{ "scratch/.*", "%.env" }` | dict |
### Customize Default Builtin behavior ### Customize Default Builtin behavior
You can customize each default builtin behavior by adding the prefered options You can customize each default builtin behavior by adding the preferred options
into the table that is passed into `require("telescope").setup()`. into the table that is passed into `require("telescope").setup()`.
Example: Example:
@@ -246,7 +247,7 @@ require("telescope").setup {
mappings = { mappings = {
i = { i = {
["<c-d>"] = require("telescope.actions").delete_buffer, ["<c-d>"] = require("telescope.actions").delete_buffer,
-- or right hand side can also be a the name of the action as string -- Right hand side can also be the name of the action as a string
["<c-d>"] = "delete_buffer", ["<c-d>"] = "delete_buffer",
}, },
n = { n = {
@@ -259,7 +260,7 @@ require("telescope").setup {
} }
}, },
extensions = { extensions = {
-- your extension config goes in here -- Your extension config goes in here
} }
} }
``` ```
@@ -288,7 +289,9 @@ the `default_mappings` table.
Much like [built-in pickers](#pickers), there are a number of Much like [built-in pickers](#pickers), there are a number of
[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: [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---> <!-- TODO: add custom action in addition to a function that gets ran after a given action--->
```lua ```lua
-- Built-in actions -- Built-in actions
@@ -336,7 +339,7 @@ require('telescope').setup{
``` ```
For a [picker](#pickers) specific remapping, it can be done by setting For a [picker](#pickers) specific remapping, it can be done by setting
its `attach_mappings` key to a function, like this its `attach_mappings` key to a function, like so:
```lua ```lua
local actions = require('telescope.actions') local actions = require('telescope.actions')
@@ -353,7 +356,7 @@ require('telescope.builtin').fd({ -- or new custom picker's attach_mappings fiel
-- Code here -- Code here
end) end)
-- You can also enhance an action with pre and post action which will run before of after an action -- You can also enhance an action with pre and post action, which will run before of after an action
action_set.select:enhance({ action_set.select:enhance({
pre = function() pre = function()
-- Will run before actions.select_default -- Will run before actions.select_default
@@ -376,7 +379,7 @@ require('telescope.builtin').fd({ -- or new custom picker's attach_mappings fiel
require'telescope.builtin'.git_branches({ attach_mappings = function(_, map) require'telescope.builtin'.git_branches({ attach_mappings = function(_, map)
map('i', '<c-d>', actions.git_delete_branch) -- this action already exist map('i', '<c-d>', actions.git_delete_branch) -- this action already exist
map('n', '<c-d>', actions.git_delete_branch) -- this action already exist map('n', '<c-d>', actions.git_delete_branch) -- this action already exist
-- for more actions look at lua/telescope/actions/init.lua -- For more actions look at lua/telescope/actions/init.lua
return true return true
end}) end})
``` ```
@@ -406,7 +409,7 @@ Built-in functions. Ready to be bound to any key you like. :smile:
#### Options for builtin.live_grep #### Options for builtin.live_grep
| Keys | Description | Options | | Keys | Description | Options |
|------------------------|------------------------------------------------------------------------------------|--------------| |------------------------|------------------------------------------------------------------------------------|---------|
| `grep_open_files` | Restrict live_grep to currently open files, mutually exclusive with `search_dirs` | boolean | | `grep_open_files` | Restrict live_grep to currently open files, mutually exclusive with `search_dirs` | boolean |
| `search_dirs` | List of directories to search in, mutually exclusive with `grep_open_files` | list | | `search_dirs` | List of directories to search in, mutually exclusive with `grep_open_files` | list |
@@ -457,15 +460,15 @@ For the `*_symbols` and `*_diagnostics` LSP pickers, there is a special filterin
search. When in insert mode while the picker is open, type `:` and then press `<C-l>` to get an autocomplete menu search. When in insert mode while the picker is open, type `:` and then press `<C-l>` to get an autocomplete menu
filled with all of the possible filters you can use. filled with all of the possible filters you can use.
i.e. while using the `lsp_document_symbols` picker, adding `:methods:` to your query filters out any document I.e. while using the `lsp_document_symbols` picker, adding `:methods:` to your query filters out any
document symbols that are not recognized as methods by treesitter. document symbols not recognized as methods by treesitter.
### Git Pickers ### Git Pickers
| Functions | Description | | Functions | Description |
|-------------------------------------|---------------------------------------------------------------------------------------------------------------| |-------------------------------------|------------------------------------------------------------------------------------------------------------|
| `builtin.git_commits` | Lists git commits with diff preview and on enter checkout the commit. | | `builtin.git_commits` | Lists git commits with diff preview and checks them out on `<cr>` |
| `builtin.git_bcommits` | Lists buffer's git commits with diff preview and checkouts it out on enter. | | `builtin.git_bcommits` | Lists buffer's git commits with diff preview and checks them out on `<cr>` |
| `builtin.git_branches` | Lists all branches with log preview, checkout action `<cr>`, track action `<C-t>` and rebase action`<C-r>` | | `builtin.git_branches` | Lists all branches with log preview, checkout action `<cr>`, track action `<C-t>` and rebase action`<C-r>` |
| `builtin.git_status` | Lists current changes per file with diff preview and add action. (Multi-selection still WIP) | | `builtin.git_status` | Lists current changes per file with diff preview and add action. (Multi-selection still WIP) |
| `builtin.git_stash` | Lists stash items in current repository with ability to apply them on `<cr>` | | `builtin.git_stash` | Lists stash items in current repository with ability to apply them on `<cr>` |
@@ -473,7 +476,7 @@ document symbols that are not recognized as methods by treesitter.
### Treesitter Picker ### Treesitter Picker
| Functions | Description | | Functions | Description |
|-------------------------------------|---------------------------------------------------------------------------------------------| |-------------------------------------|---------------------------------------------------|
| `builtin.treesitter` | Lists Function names, variables, from Treesitter! | | `builtin.treesitter` | Lists Function names, variables, from Treesitter! |
### Lists Picker ### Lists Picker
@@ -481,8 +484,8 @@ document symbols that are not recognized as methods by treesitter.
| Functions | Description | | Functions | Description |
|-------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |-------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `builtin.planets` | Use the telescope... | | `builtin.planets` | Use the telescope... |
| `builtin.builtin` | Lists Built-in pickers and run them on enter. | | `builtin.builtin` | Lists Built-in pickers and run them on `<cr>`. |
| `builtin.reloader` | Lists lua modules and reload them on enter. | | `builtin.reloader` | Lists Lua modules and reload them on `<cr>`. |
| `builtin.symbols` | Lists symbols inside a file `data/telescope-sources/*.json` found in your rtp. More info and symbol sources can be found [here](https://github.com/nvim-telescope/telescope-symbols.nvim) | | `builtin.symbols` | Lists symbols inside a file `data/telescope-sources/*.json` found in your rtp. More info and symbol sources can be found [here](https://github.com/nvim-telescope/telescope-symbols.nvim) |
## Previewers ## Previewers
@@ -498,14 +501,15 @@ document symbols that are not recognized as methods by treesitter.
The default previewers are from now on `vim_buffer_` previewers. They use vim buffers for displaying files The default previewers are from now on `vim_buffer_` previewers. They use vim buffers for displaying files
and use tree-sitter or regex for file highlighting. and use tree-sitter or regex for file highlighting.
These previewers are guessing the filetype of the selected file, so there might be cases where it misses, These previewers are guessing the filetype of the selected file, so there might be cases where they miss,
thus leading to wrong highlights. This is because we can't determine the filetype in the traditional way leading to wrong highlights. This is because we can't determine the filetype in the traditional way:
(we don't do `bufload`. We read the file async with `vim.loop.fs_` and attach only a highlighter), because we can't We don't do `bufload` and instead read the file asynchronously with `vim.loop.fs_` and attach only a
execute autocommands, otherwise the speed of the previewer would slow down considerably. highlighter; otherwise the speed of the previewer would slow down considerably.
If you want to configure more filetypes take a look at If you want to configure more filetypes, take a look at
[plenary wiki](https://github.com/nvim-lua/plenary.nvim#plenaryfiletype). [plenary wiki](https://github.com/nvim-lua/plenary.nvim#plenaryfiletype).
If you want to configure the `vim_buffer_` previewer, e.g. you want the line to wrap do this: If you want to configure the `vim_buffer_` previewer (e.g. you want the line to wrap), do this:
```vim ```vim
autocmd User TelescopePreviewerLoaded setlocal wrap autocmd User TelescopePreviewerLoaded setlocal wrap
``` ```
@@ -538,24 +542,26 @@ We have some built in themes but are looking for more cool options.
![dropdown](https://i.imgur.com/SorAcXv.png) ![dropdown](https://i.imgur.com/SorAcXv.png)
| Themes | Description | | Themes | Description |
|--------------------------|-----------------------------------------------------------------------| |--------------------------|---------------------------------------------------------------------------------------------|
| `themes.get_dropdown` | A list like centered list. [dropdown](https://i.imgur.com/SorAcXv.png)| | `themes.get_dropdown` | A list like centered list. [dropdown](https://i.imgur.com/SorAcXv.png) |
| `themes.get_ivy` | Bottom panel overlay. [Ivy #771](https://github.com/nvim-telescope/telescope.nvim/pull/771)| | `themes.get_ivy` | Bottom panel overlay. [Ivy #771](https://github.com/nvim-telescope/telescope.nvim/pull/771) |
To use a theme, simply append it to a built-in function: To use a theme, simply append it to a built-in function:
```vim ```vim
nnoremap <Leader>f :lua require'telescope.builtin'.find_files(require('telescope.themes').get_dropdown({}))<cr> nnoremap <Leader>f :lua require'telescope.builtin'.find_files(require('telescope.themes').get_dropdown({}))<cr>
" Change an option " Change an option
nnoremap <Leader>f :lua require'telescope.builtin'.find_files(require('telescope.themes').get_dropdown({ winblend = 10 }))<cr> nnoremap <Leader>f :lua require'telescope.builtin'.find_files(require('telescope.themes').get_dropdown({ winblend = 10 }))<cr>
``` ```
or use with command:
Or use with a command:
```vim ```vim
Telescope find_files theme=get_dropdown Telescope find_files theme=get_dropdown
``` ```
Themes should work with every `telescope.builtin` function. If you wish to Themes should work with every `telescope.builtin` function. If you wish to make a theme,
make a theme, check out `lua/telescope/themes.lua`. check out `lua/telescope/themes.lua`.
## Autocmds ## Autocmds
@@ -566,34 +572,38 @@ Telescope user autocmds:
| `User TelescopeFindPre` | Do it before Telescope creates all the floating windows | | `User TelescopeFindPre` | Do it before Telescope creates all the floating windows |
| `User TelescopePreviewerLoaded` | Do it after Telescope previewer window is created | | `User TelescopePreviewerLoaded` | Do it after Telescope previewer window is created |
## Extensions ## Extensions
Telescope provides the capabilities to create & register extensions, which improve telescope in a variety of ways. Telescope provides the capabilities to create & register extensions, which improve telescope in a
variety of ways.
Some extensions provide integration with external tools, outside of the scope of `builtins`. Others provide performance Some extensions provide integration with external tools, outside of the scope of `builtins`.
enhancements by using compiled C and interfacing directly with Lua. Others provide performance enhancements by using compiled C and interfacing directly with Lua.
### Loading extensions ### Loading extensions
To load an extension, use the `load_extension` function as shown in the example below: To load an extension, use the `load_extension` function as shown in the example below:
```lua ```lua
-- This will load fzy_native and have it override the default file sorter -- This will load fzy_native and have it override the default file sorter
require('telescope').load_extension('fzy_native') require('telescope').load_extension('fzy_native')
``` ```
You may skip explicitly loading extensions (they will then be lazy-loaded), but tab completions will not be available right away. You may skip explicitly loading extensions (they will then be lazy-loaded), but tab completions will
not be available right away.
### Accessing pickers from extensions ### Accessing pickers from extensions
Pickers from extensions are added to the `:Telescope` command under their respective name. Pickers from extensions are added to the `:Telescope` command under their respective name.
For example: For example:
```viml ```viml
" Run the `configurations` picker from nvim-dap " Run the `configurations` picker from nvim-dap
:Telescope dap configurations :Telescope dap configurations
``` ```
They can also be called directly from lua: They can also be called directly from Lua:
```lua ```lua
-- Run the `configurations` picker from nvim-dap -- Run the `configurations` picker from nvim-dap
require('telescope').extensions.dap.configurations() require('telescope').extensions.dap.configurations()
@@ -601,7 +611,7 @@ require('telescope').extensions.dap.configurations()
### Community Extensions ### Community Extensions
For a list of community extensions, please consult the wiki: [Extensions](https://github.com/nvim-telescope/telescope.nvim/wiki/Extensions) For a list of community extensions, please consult the Wiki: [Extensions](https://github.com/nvim-telescope/telescope.nvim/wiki/Extensions)
## API ## API
<!-- TODO: need to provide working examples for every api --> <!-- TODO: need to provide working examples for every api -->
@@ -621,8 +631,7 @@ Finder:new{
### Picker ### Picker
<!-- TODO: this section need some love, an in-depth explanation will be appreciated it need some in depth explanation --> <!-- TODO: this section need some love, an in-depth explanation will be appreciated it need some in depth explanation -->
<!-- TODO what is pickers --> <!-- TODO what is pickers -->
This section is an overview of how custom pickers can be created any configured. This section is an overview of how custom pickers can be created and configured.
```lua ```lua
-- lua/telescope/pickers.lua -- lua/telescope/pickers.lua
@@ -672,7 +681,8 @@ For more details on available strategies and configuration options,
see `:help telescope.layout`. see `:help telescope.layout`.
Some options for configuring sizes in layouts are "resolvable". Some options for configuring sizes in layouts are "resolvable".
This means that they can take different forms, and will be interpreted differently according to which form they take. This means that they can take different forms, and will be interpreted differently according
to which form they take.
For example, if we wanted to set the `width` of a picker using the `vertical` For example, if we wanted to set the `width` of a picker using the `vertical`
layout strategy to 50% of the screen width, we would specify that width layout strategy to 50% of the screen width, we would specify that width
as `0.5`, but if we wanted to specify the `width` to be exactly 80 as `0.5`, but if we wanted to specify the `width` to be exactly 80
@@ -681,11 +691,14 @@ For more details on resolving sizes, see `:help telescope.resolve`.
As an example, if we wanted to specify the layout strategy and width, As an example, if we wanted to specify the layout strategy and width,
but only for this instance, we could do something like: but only for this instance, we could do something like:
``` ```
:lua require('telescope.builtin').find_files({layout_strategy='vertical',layout_config={width=0.5}}) :lua require('telescope.builtin').find_files({layout_strategy='vertical',layout_config={width=0.5}})
``` ```
or if we wanted to change the width for every time we use the `vertical`
If we wanted to change the width for every time we use the `vertical`
layout strategy, we could add the following to our `setup()` call: layout strategy, we could add the following to our `setup()` call:
``` ```
require('telescope').setup({ require('telescope').setup({
defaults = { defaults = {
@@ -701,8 +714,8 @@ require('telescope').setup({
## Vim Commands ## Vim Commands
All `telescope.nvim` functions are wrapped in `vim` commands for easy access, its All `telescope.nvim` functions are wrapped in `vim` commands for easy access,
supports tab completions and settings options. tab completions and setting options.
```viml ```viml
" Show all builtin pickers " Show all builtin pickers
@@ -715,8 +728,8 @@ supports tab completions and settings options.
" Setting options " Setting options
:Telescope find_files prompt_prefix=🔍 :Telescope find_files prompt_prefix=🔍
" If option is table type in lua code ,you can use `,` connect each command string eg: " If option is table type in Lua code, you can use `,` to connect each command string, e.g.:
" find_command,vimgrep_arguments they are both table type. so config it in commandline like " find_command,vimgrep_arguments are both table type. So configure it on command-line like so:
:Telescope find_files find_command=rg,--ignore,--hidden,--files prompt_prefix=🔍 :Telescope find_files find_command=rg,--ignore,--hidden,--files prompt_prefix=🔍
``` ```
@@ -736,7 +749,7 @@ and some other functions can be easily changed in custom pickers or built-in fun
<!-- TODO: insert a list of available options like previewer and prompt prefix --> <!-- TODO: insert a list of available options like previewer and prompt prefix -->
```lua ```lua
-- Disable preview for find files -- Disable preview for find_files
nnoremap <leader>ff :lua require('telescope.builtin').find_files({previewer = false})<cr> nnoremap <leader>ff :lua require('telescope.builtin').find_files({previewer = false})<cr>
-- Change change prompt prefix for find_files builtin function: -- Change change prompt prefix for find_files builtin function:
@@ -749,31 +762,30 @@ nnoremap <leader>fg :Telescope live_grep prompt_prefix=🔍<cr>
There are 10 highlight groups you can play around with in order to meet your needs: There are 10 highlight groups you can play around with in order to meet your needs:
```viml ```viml
highlight TelescopeSelection guifg=#D79921 gui=bold " selected item highlight TelescopeSelection guifg=#D79921 gui=bold " Selected item
highlight TelescopeSelectionCaret guifg=#CC241D " selection caret highlight TelescopeSelectionCaret guifg=#CC241D " Selection caret
highlight TelescopeMultiSelection guifg=#928374 " multisections highlight TelescopeMultiSelection guifg=#928374 " Multisections
highlight TelescopeNormal guibg=#00000 " floating windows created by telescope. highlight TelescopeNormal guibg=#00000 " Floating windows created by telescope
" Border highlight groups. " Border highlight groups
highlight TelescopeBorder guifg=#ffffff highlight TelescopeBorder guifg=#ffffff
highlight TelescopePromptBorder guifg=#ffffff highlight TelescopePromptBorder guifg=#ffffff
highlight TelescopeResultsBorder guifg=#ffffff highlight TelescopeResultsBorder guifg=#ffffff
highlight TelescopePreviewBorder guifg=#ffffff highlight TelescopePreviewBorder guifg=#ffffff
" Used for highlighting characters that you match. " Highlight characters your input matches
highlight TelescopeMatching guifg=blue highlight TelescopeMatching guifg=blue
" Used for the prompt prefix " Color the prompt prefix
highlight TelescopePromptPrefix guifg=red highlight TelescopePromptPrefix guifg=red
``` ```
To checkout the default values of the highlight groups, checkout `plugin/telescope.vim` To checkout the default values of the highlight groups, check out `plugin/telescope.vim`
### How to add autocmds to telescope prompt ? ### How to add autocmds to telescope prompt ?
`TelescopePrompt` is the prompt Filetype. You can customize the Filetype as you would normally. `TelescopePrompt` is the prompt Filetype. You can customize the Filetype as you would normally.
## Contributing ## Contributing
All contributions are welcome! Just open a pull request. All contributions are welcome! Just open a pull request.