================================================================================
                                                                *telescope.nvim*

Telescope.nvim is a plugin for fuzzy finding and neovim. It helps you search,
filter, find and pick things in Lua.

To find out more:
https://github.com/nvim-telescope/telescope.nvim

  :h telescope.setup
  :h telescope.builtin
  :h telescope.layout
  :h telescope.actions

telescope.setup({opts})                                    *telescope.setup()*
    Setup function to be run by user. Configures the defaults, extensions and
    other aspects of telescope.


    Valid keys for {opts.defaults}

                                                *telescope.defaults.border*
    border: ~
        Boolean defining if borders are added to Telescope windows.

        Default: true

                                          *telescope.defaults.cache_picker*
    cache_picker: ~
        This field handles the configuration for picker caching.
        By default it is a table, with default values (more below).
        To disable caching, set it to false.

        Caching preserves all previous multi selections and results and
        therefore may result in slowdown or increased RAM occupation
        if too many pickers (`cache_picker.num_pickers`) or entries
        ('cache_picker.limit_entries`) are cached.

        Fields:
          - num_pickers:      The number of pickers to be cached.
                              Set to -1 to preserve all pickers of your session.
                              If passed to a picker, the cached pickers with
                              indices larger than `cache_picker.num_pickers` will
                              be cleared.
                              Default: 1
          - limit_entries:    The amount of entries that will be written in the
                              Default: 1000


                                      *telescope.defaults.default_mappings*
    default_mappings: ~
        Not recommended to use except for advanced users.

        Will allow you to completely remove all of telescope's default maps
        and use your own.


                                 *telescope.defaults.dynamic_preview_title*
    dynamic_preview_title: ~
        Will change the title of the preview window dynamically, where it
        is supported. Means the preview window will for example show the
        full filename.

        Default: false

                                          *telescope.defaults.entry_prefix*
    entry_prefix: ~
        Prefix in front of each result entry. Current selection not included.

        Default: '  '

                                               *telescope.defaults.history*
    history: ~
          This field handles the configuration for prompt history.
          By default it is a table, with default values (more below).
          To disable history, set it to false.

          Currently mappings still need to be added, Example:
            mappings = {
              i = {
                ["<C-Down>"] = require('telescope.actions').cycle_history_next,
                ["<C-Up>"] = require('telescope.actions').cycle_history_prev,
              },
            },

          Fields:
            - path:    The path to the telescope history as string.
                       default: stdpath("data")/telescope_history
            - limit:   The amount of entries that will be written in the
                       history.
                       Warning: If limit is set to nil it will grown unbound.
                       default: 100
            - handler: A lua function that implements the history.
                       This is meant as a developer setting for extensions to
                       override the history handling, e.g.,
                       https://github.com/nvim-telescope/telescope-smart-history.nvim,
                       which allows context sensitive (cwd + picker) history.

                       Default:
                       require('telescope.actions.history').get_simple_history


                                         *telescope.defaults.layout_config*
    layout_config: ~
        Determines the default configuration values for layout strategies.
        See |telescope.layout| for details of the configurations options for
        each strategy.

        Allows setting defaults for all strategies as top level options and
        for overriding for specific options.
        For example, the default values below set the default width to 80% of
        the screen width for all strategies except 'center', which has width
        of 50% of the screen width.

        Default: {
          center = {
            preview_cutoff = 40
          },
          cursor = {
            preview_cutoff = 40
          },
          height = 0.9,
          horizontal = {
            preview_cutoff = 120,
            prompt_position = "bottom"
          },
          vertical = {
            preview_cutoff = 40
          },
          width = 0.8
        }


                                       *telescope.defaults.layout_strategy*
    layout_strategy: ~
        Determines the default layout of Telescope pickers.
        See |telescope.layout| for details of the available strategies.

        Default: 'horizontal'

                                              *telescope.defaults.mappings*
    mappings: ~
        Your mappings to override telescope's default mappings.

        Format is:
        {
          mode = { ..keys }
        }

        where {mode} is the one character letter for a mode
        ('i' for insert, 'n' for normal).

        For example:

        mappings = {
          i = {
            ["<esc>"] = require('telescope.actions').close,
          },
        }


        To disable a keymap, put [map] = false
          So, to not map "<C-n>", just put

            ...,
            ["<C-n>"] = false,
            ...,

          Into your config.


        otherwise, just set the mapping to the function that you want it to
        be.

            ...,
            ["<C-i>"] = require('telescope.actions').select_default,
            ...,

        If the function you want is part of `telescope.actions`, then you can
        simply give a string.
          For example, the previous option is equivalent to:

            ...,
            ["<C-i>"] = "select_default",
            ...,

        You can also add other mappings using tables with `type = "command"`.
          For example:

            ...,
            ["jj"] = { "<esc>", type = "command" },
            ["kk"] = { "<cmd>echo \"Hello, World!\"<cr>", type = "command" },)
            ...,


                                          *telescope.defaults.path_display*
    path_display: ~
        Determines how file paths are displayed

        path_display can be set to an array with a combination of:
        - "hidden"    hide file names
        - "tail"      only display the file name, and not the path
        - "absolute"  display absolute paths
        - "shorten"   only display the first character of each directory in
                      the path

        You can also specify the number of characters of each directory name
        to keep by setting `path_display.shorten = num`.
          e.g. for a path like
            `alpha/beta/gamma/delta.txt`
          setting `path_display.shorten = 1` will give a path like:
            `a/b/g/delta.txt`
          Similarly, `path_display.shorten = 2` will give a path like:
            `al/be/ga/delta.txt`

        path_display can also be set to 'hidden' string to hide file names

        path_display can also be set to a function for custom formatting of
        the path display. Example:

            -- Format path as "file.txt (path\to\file\)"
            path_display = function(opts, path)
              local tail = require("telescope.utils").path_tail(path)
              return string.format("%s (%s)", tail, path)
            end,

        Default: {}

                                         *telescope.defaults.prompt_prefix*
    prompt_prefix: ~
        Will be shown in front of the prompt.

        Default: '> '

                                       *telescope.defaults.scroll_strategy*
    scroll_strategy: ~
        Determines what happens you try to scroll past view of the picker.

        Available options are:
        - "cycle" (default)
        - "limit"

                                       *telescope.defaults.selection_caret*
    selection_caret: ~
        Will be shown in front of the selection.

        Default: '> '

                                    *telescope.defaults.selection_strategy*
    selection_strategy: ~
        Determines how the cursor acts after each sort iteration.

        Available options are:
        - "reset" (default)
        - "follow"
        - "row"
        - "closest"

                                      *telescope.defaults.sorting_strategy*
    sorting_strategy: ~
        Determines the direction "better" results are sorted towards.

        Available options are:
        - "descending" (default)
        - "ascending"

    Parameters: ~
        {opts} (table)  Configuration opts. Keys: defaults, extensions


telescope.register_extension({mod})           *telescope.register_extension()*
    Register an extension. To be used by plugin authors.


    Parameters: ~
        {mod} (table)  Module


telescope.load_extension({name})                  *telescope.load_extension()*
    Load an extension.


    Parameters: ~
        {name} (string)  Name of the extension


telescope.extensions()                                *telescope.extensions()*
    Use telescope.extensions to reference any extensions within your
    configuration.
    While the docs currently generate this as a function, it's actually a
    table. Sorry.




================================================================================
                                                             *telescope.command*

Telescope commands can be called through two apis, the lua api and the viml
api.

The lua api is the more direct way to interact with Telescope, as you directly
call the lua functions that Telescope defines. It can be called in a lua file
using commands like:
`require("telescope.builtin").find_files({hidden=true, layout_config={prompt_position="top"}})`
If you want to use this api from a vim file you should prepend `lua` to the
command, as below:
`lua require("telescope.builtin").find_files({hidden=true, layout_config={prompt_position="top"}})`
If you want to use this api from a neovim command line you should prepend
`:lua` to the command, as below:
`:lua require("telescope.builtin").find_files({hidden=true, layout_config={prompt_position="top"}})`

The viml api is more indirect, as first the command must be parsed to the
relevant lua equivalent, which brings some limitations. The viml api can be
called using commands like:
`:Telescope find_files hidden=true layout_config={"prompt_position":"top"}`
This involves setting options using an `=` and using viml syntax for lists and
dictionaries when the corresponding lua function requires a table.

One limitation of the viml api is that there can be no spaces in any of the
options. For example, if you want to use the `cwd` option for `find_files` to
specify that you only want to search within the folder `/foo bar/subfolder/`
you could not do that using the viml api, as the path name contains a space.
Similarly, you could NOT set the `prompt_position` to `"top"` using the
following command:
`:Telescope find_files layout_config={ "prompt_position" : "top" }`
as there are spaces in the option.



================================================================================
                                                             *telescope.builtin*

Telescope Builtins is a collection of community maintained pickers to support
common workflows. It can be used as reference when writing PRs, Telescope
extensions, your own custom pickers, or just as a discovery tool for all of the
amazing pickers already shipped with Telescope!

Any of these functions can just be called directly by doing:

:lua require('telescope.builtin').$NAME_OF_PICKER()

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
})

You can also pass default configurations to builtin pickers. These options will
also be added if the picker is executed with `Telescope find_files`.

require("telescope").setup {
  pickers = {
    buffers = {
      show_all_buffers = true,
      sort_lastused = true,
      theme = "dropdown",
      previewer = false,
      mappings = {
        i = {
          ["<c-d>"] = require("telescope.actions").delete_buffer,
          -- or right hand side can also be the name of the action as string
          ["<c-d>"] = "delete_buffer",
        },
        n = {
          ["<c-d>"] = require("telescope.actions").delete_buffer,
        }
      }
    }
  }
}

This will use the default configuration options. Other configuration options
are still in flux at the moment

builtin.live_grep({opts})                                *builtin.live_grep()*
    Search for a string and get results live as you type (respecting
    .gitignore)


    Parameters: ~
        {opts} (table)  options to pass to the picker

    Fields: ~
        {cwd}             (string)    root dir to search from (default is cwd,
                                      use utils.buffer_dir() to search
                                      relative to open buffer)
        {grep_open_files} (boolean)   if true, restrict search to open files
                                      only, mutually exclusive with
                                      `search_dirs`
        {search_dirs}     (table)     directory/directories to search in,
                                      mutually exclusive with
                                      `grep_open_files`
        {additional_args} (function)  function(opts) which returns a table of
                                      additional arguments to be passed on


builtin.grep_string({opts})                            *builtin.grep_string()*
    Searches for the string under your cursor in your current working directory


    Parameters: ~
        {opts} (table)  options to pass to the picker

    Fields: ~
        {cwd}             (string)    root dir to search from (default is cwd,
                                      use utils.buffer_dir() to search
                                      relative to open buffer)
        {search}          (string)    the query to search
        {search_dirs}     (table)     directory/directories to search in
        {use_regex}       (boolean)   if true, special characters won't be
                                      escaped, allows for using regex (default
                                      is false)
        {additional_args} (function)  function(opts) which returns a table of
                                      additional arguments to be passed on


builtin.find_files({opts})                              *builtin.find_files()*
    Search for files (respecting .gitignore)


    Parameters: ~
        {opts} (table)  options to pass to the picker

    Fields: ~
        {cwd}          (string)   root dir to search from (default is cwd, use
                                  utils.buffer_dir() to search relative to
                                  open buffer)
        {find_command} (table)    command line arguments for `find_files` to
                                  use for the search, overrides default config
        {follow}       (boolean)  if true, follows symlinks (i.e. uses `-L`
                                  flag for the `find` command)
        {hidden}       (boolean)  determines whether to show hidden files or
                                  not (default is false)
        {no_ignore}    (boolean)  show files ignored by .gitignore, .ignore,
                                  etc. (default is false)
        {search_dirs}  (table)    directory/directories to search in


builtin.fd()                                                    *builtin.fd()*
    This is an alias for the `find_files` picker



builtin.file_browser({opts})                          *builtin.file_browser()*
    Lists files and folders in your current working directory, open files,
    navigate your filesystem, and create new files and folders
    - Default keymaps:
      - `<cr>`: opens the currently selected file, or navigates to the
        currently selected directory
      - `<C-e>`: creates new file in current directory, creates new directory
        if the name contains a trailing '/'
        - Note: you can create files nested into several directories with
          `<C-e>`, i.e. `lua/telescope/init.lua` would create the file
          `init.lua` inside of `lua/telescope` and will create the necessary
          folders (similar to how `mkdir -p` would work) if they do not already
          exist


    Parameters: ~
        {opts} (table)  options to pass to the picker

    Fields: ~
        {cwd}      (string)   root dir to browse from (default is cwd, use
                              utils.buffer_dir() to search relative to open
                              buffer)
        {depth}    (number)   file tree depth to display (default is 1)
        {dir_icon} (string)   change the icon for a directory. default: 
        {hidden}   (boolean)  determines whether to show hidden files or not
                              (default is false)


builtin.treesitter()                                    *builtin.treesitter()*
    Lists function names, variables, and other symbols from treesitter queries
    - Default keymaps:
      - `<C-l>`: show autocompletion menu to prefilter your query by kind of ts
        node you want to see (i.e. `:var:`)


    Fields: ~
        {show_line} (boolean)  if true, shows the row:column that the result
                               is found at (default is true)


builtin.current_buffer_fuzzy_find({opts})*builtin.current_buffer_fuzzy_find()*
    Live fuzzy search inside of the currently open buffer


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.tags({opts})                                          *builtin.tags()*
    Lists tags in current directory with tag location file preview (users are
    required to run ctags -R to generate tags or update when introducing new
    changes)


    Parameters: ~
        {opts} (table)  options to pass to the picker

    Fields: ~
        {ctags_file} (string)   specify a particular ctags file to use
        {show_line}  (boolean)  if true, shows the content of the line the tag
                                is found on in the picker (default is true)


builtin.current_buffer_tags({opts})            *builtin.current_buffer_tags()*
    Lists all of the tags for the currently open buffer, with a preview


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.git_files({opts})                                *builtin.git_files()*
    Fuzzy search for files tracked by Git. This command lists the output of the
    `git ls-files` command, respects .gitignore, and optionally ignores
    untracked files
    - Default keymaps:
      - `<cr>`: opens the currently selected file


    Parameters: ~
        {opts} (table)  options to pass to the picker

    Fields: ~
        {show_untracked}     (boolean)  if true, adds `--others` flag to
                                        command and shows untracked files
                                        (default is true)
        {recurse_submodules} (boolean)  if true, adds the
                                        `--recurse-submodules` flag to command
                                        (default is false)


builtin.git_commits({opts})                            *builtin.git_commits()*
    Lists commits for current directory with diff preview
    - Default keymaps:
      - `<cr>`: checks out the currently selected commit
      - `<C-r>m`: resets current branch to selected commit using mixed mode
      - `<C-r>s`: resets current branch to selected commit using soft mode
      - `<C-r>h`: resets current branch to selected commit using hard mode


    Parameters: ~
        {opts} (table)  options to pass to the picker

    Fields: ~
        {cwd} (string)  specify the path of the repo


builtin.git_bcommits({opts})                          *builtin.git_bcommits()*
    Lists commits for current buffer with diff preview
    - Default keymaps or your overriden `select_` keys:
      - `<cr>`: checks out the currently selected commit
      - `<c-v>`: opens a diff in a vertical split
      - `<c-x>`: opens a diff in a horizontal split
      - `<c-t>`: opens a diff in a new tab


    Parameters: ~
        {opts} (table)  options to pass to the picker

    Fields: ~
        {cwd}          (string)  specify the path of the repo
        {current_file} (string)  specify the current file that should be used
                                 for bcommits (default: current buffer)


builtin.git_branches({opts})                          *builtin.git_branches()*
    List branches for current directory, with output from `git log --oneline`
    shown in the preview window
    - Default keymaps:
      - `<cr>`: checks out the currently selected branch
      - `<C-t>`: tracks currently selected branch
      - `<C-r>`: rebases currently selected branch
      - `<C-a>`: creates a new branch, with confirmation prompt before creation
      - `<C-d>`: deletes the currently selected branch, with confirmation
        prompt before deletion
      - `<C-y>`: merges the currently selected branch, with confirmation prompt
        before deletion


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.git_status({opts})                              *builtin.git_status()*
    Lists git status for current directory
    - Default keymaps:
      - `<Tab>`: stages or unstages the currently selected file
      - `<cr>`: opens the currently selected file


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.git_stash({opts})                                *builtin.git_stash()*
    Lists stash items in current repository
    - Default keymaps:
      - `<cr>`: runs `git apply` for currently selected stash


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.builtin({opts})                                    *builtin.builtin()*
    Lists all of the community maintained pickers built into Telescope


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.planets({opts})                                    *builtin.planets()*
    Use the telescope...


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.symbols({opts})                                    *builtin.symbols()*
    Lists symbols inside of `data/telescope-sources/*.json` found in your
    runtime path or found in `stdpath("data")/telescope/symbols/*.json`. The
    second path can be customized. We provide a couple of default symbols which
    can be found in https://github.com/nvim-telescope/telescope-symbols.nvim.
    This repos README also provides more information about the format in which
    the symbols have to be.


    Parameters: ~
        {opts} (table)  options to pass to the picker

    Fields: ~
        {symbol_path} (string)  specify the second path. Default:
                                `stdpath("data")/telescope/symbols/*.json`
        {sources}     (table)   specify a table of sources you want to load
                                this time


builtin.commands({opts})                                  *builtin.commands()*
    Lists available plugin/user commands and runs them on `<cr>`


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.quickfix({opts})                                  *builtin.quickfix()*
    Lists items in the quickfix list, jumps to location on `<cr>`


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.loclist({opts})                                    *builtin.loclist()*
    Lists items from the current window's location list, jumps to location on
    `<cr>`


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.oldfiles({opts})                                  *builtin.oldfiles()*
    Lists previously open files, opens on `<cr>`


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.command_history({opts})                    *builtin.command_history()*
    Lists commands that were executed recently, and reruns them on `<cr>`
    - Default keymaps:
      - `<C-e>`: open the command line with the text of the currently selected
        result populated in it


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.search_history({opts})                      *builtin.search_history()*
    Lists searches that were executed recently, and reruns them on `<cr>`
    - Default keymaps:
      - `<C-e>`: open a search window with the text of the currently selected
        search result populated in it


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.resume({opts})                                      *builtin.resume()*
    Opens the previous picker in the identical state (incl. multi selections)
    - Notes:
      - Requires `cache_picker` in setup or when having invoked pickers, see
        |telescope.defaults.cache_picker|


    Parameters: ~
        {opts} (table)  options to pass to the picker

    Fields: ~
        {cache_index} (number)  what picker to resume, where 1 denotes most
                                recent (default 1)


builtin.pickers({opts})                                    *builtin.pickers()*
    Opens a picker over previously cached pickers in there preserved states
    (incl. multi selections)
    - Default keymaps:
      - `<C-x>`: delete the selected cached picker
    - Notes:
      - Requires `cache_picker` in setup or when having invoked pickers, see
        |telescope.defaults.cache_picker|


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.vim_options({opts})                            *builtin.vim_options()*
    Lists vim options, allows you to edit the current value on `<cr>`


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.help_tags({opts})                                *builtin.help_tags()*
    Lists available help tags and opens a new window with the relevant help
    info on `<cr>`


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.man_pages({opts})                                *builtin.man_pages()*
    Lists manpage entries, opens them in a help window on `<cr>`


    Parameters: ~
        {opts} (table)  options to pass to the picker

    Fields: ~
        {sections} (table)  a list of sections to search, use `{ "ALL" }` to
                            search in all sections


builtin.reloader({opts})                                  *builtin.reloader()*
    Lists lua modules and reloads them on `<cr>`


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.buffers({opts})                                    *builtin.buffers()*
    Lists open buffers in current neovim instance, opens selected buffer on
    `<cr>`


    Parameters: ~
        {opts} (table)  options to pass to the picker

    Fields: ~
        {show_all_buffers}      (boolean)  if true, show all buffers,
                                           including unloaded buffers (default
                                           true)
        {ignore_current_buffer} (boolean)  if true, don't show the current
                                           buffer in the list (default false)
        {only_cwd}              (boolean)  if true, only show buffers in the
                                           current working directory (default
                                           false)
        {sort_lastused}         (boolean)  Sorts current and last buffer to
                                           the top and selects the lastused
                                           (default false)
        {sort_mru}              (boolean)  Sorts all buffers after most recent
                                           used. Not just the current and last
                                           one (default false)
        {bufnr_width}           (number)   Defines the width of the buffer
                                           numbers in front of the filenames


builtin.colorscheme({opts})                            *builtin.colorscheme()*
    Lists available colorschemes and applies them on `<cr>`


    Parameters: ~
        {opts} (table)  options to pass to the picker

    Fields: ~
        {enable_preview} (boolean)  if true, will preview the selected color


builtin.marks({opts})                                        *builtin.marks()*
    Lists vim marks and their value, jumps to the mark on `<cr>`


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.registers({opts})                                *builtin.registers()*
    Lists vim registers, pastes the contents of the register on `<cr>`
    - Default keymaps:
      - `<C-e>`: edit the contents of the currently selected register


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.keymaps({opts})                                    *builtin.keymaps()*
    Lists normal mode keymappings, runs the selected keymap on `<cr>`


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.filetypes({opts})                                *builtin.filetypes()*
    Lists all available filetypes, sets currently open buffer's filetype to
    selected filetype in Telescope on `<cr>`


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.highlights({opts})                              *builtin.highlights()*
    Lists all available highlights


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.autocommands({opts})                          *builtin.autocommands()*
    Lists vim autocommands and goes to their declaration on `<cr>`


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.spell_suggest({opts})                        *builtin.spell_suggest()*
    Lists spelling suggestions for the current word under the cursor, replaces
    word with selected suggestion on `<cr>`


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.tagstack({opts})                                  *builtin.tagstack()*
    Lists the tag stack for the current window, jumps to tag on `<cr>`


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.jumplist({opts})                                  *builtin.jumplist()*
    Lists items from Vim's jumplist, jumps to location on `<cr>`


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.lsp_references({opts})                      *builtin.lsp_references()*
    Lists LSP references for word under the cursor, jumps to reference on
    `<cr>`


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.lsp_definitions({opts})                    *builtin.lsp_definitions()*
    Goto the definition of the word under the cursor, if there's only one,
    otherwise show all options in Telescope


    Parameters: ~
        {opts} (table)  options to pass to the picker

    Fields: ~
        {jump_type} (string)  how to goto definition if there is only one,
                              values: "tab", "split", "vsplit", "never"


builtin.lsp_type_definitions({opts})          *builtin.lsp_type_definitions()*
    Goto the definition of the type of the word under the cursor, if there's
    only one, otherwise show all options in Telescope


    Parameters: ~
        {opts} (table)  options to pass to the picker

    Fields: ~
        {jump_type} (string)  how to goto definition if there is only one,
                              values: "tab", "split", "vsplit", "never"

builtin.lsp_implementations({opts})            *builtin.lsp_implementations()*
    Goto the implementation of the word under the cursor if there's only one,
    otherwise show all options in Telescope


    Parameters: ~
        {opts} (table)  options to pass to the picker

    Fields: ~
        {jump_type} (string)  how to goto implementation if there is only one,
                              values: "tab", "split", "vsplit", "never"


builtin.lsp_code_actions({opts})                  *builtin.lsp_code_actions()*
    Lists any LSP actions for the word under the cursor which can be triggered
    with `<cr>`


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.lsp_range_code_actions({opts})      *builtin.lsp_range_code_actions()*
    Lists any LSP actions for a given range, that can be triggered with `<cr>`


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.lsp_document_symbols({opts})          *builtin.lsp_document_symbols()*
    Lists LSP document symbols in the current buffer
    - Default keymaps:
      - `<C-l>`: show autocompletion menu to prefilter your query by type of
        symbol you want to see (i.e. `:variable:`)


    Parameters: ~
        {opts} (table)  options to pass to the picker

    Fields: ~
        {ignore_filename} (type)          string with file to ignore
        {symbols}         (string|table)  filter results by symbol kind(s)


builtin.lsp_workspace_symbols({opts})        *builtin.lsp_workspace_symbols()*
    Lists LSP document symbols in the current workspace
    - Default keymaps:
      - `<C-l>`: show autocompletion menu to prefilter your query by type of
        symbol you want to see (i.e. `:variable:`)


    Parameters: ~
        {opts} (table)  options to pass to the picker

    Fields: ~
        {ignore_filename} (string)        file(s) to ignore
        {symbols}         (string|table)  filter results by symbol kind(s)


builtin.lsp_dynamic_workspace_symbols({opts})*builtin.lsp_dynamic_workspace_symbols()*
    Dynamically lists LSP for all workspace symbols
    - Default keymaps:
      - `<C-l>`: show autocompletion menu to prefilter your query by type of
        symbol you want to see (i.e. `:variable:`)


    Parameters: ~
        {opts} (table)  options to pass to the picker


builtin.lsp_document_diagnostics({opts})  *builtin.lsp_document_diagnostics()*
    Lists LSP diagnostics for the current buffer
    - Fields:
      - `All severity flags can be passed as `string` or `number` as per
        `:vim.lsp.protocol.DiagnosticSeverity:`
    - Default keymaps:
      - `<C-l>`: show autocompletion menu to prefilter your query with the
        diagnostic you want to see (i.e. `:warning:`)


    Parameters: ~
        {opts} (table)  options to pass to the picker

    Fields: ~
        {severity}       (string|number)  filter diagnostics by severity name
                                          (string) or id (number)
        {severity_limit} (string|number)  keep diagnostics equal or more
                                          severe wrt severity name (string) or
                                          id (number)
        {severity_bound} (string|number)  keep diagnostics equal or less
                                          severe wrt severity name (string) or
                                          id (number)
        {no_sign}        (bool)           hide LspDiagnosticSigns from Results
                                          (default is false)
        {line_width}     (number)         set length of diagnostic entry text
                                          in Results


builtin.lsp_workspace_diagnostics({opts})*builtin.lsp_workspace_diagnostics()*
    Lists LSP diagnostics for the current workspace if supported, otherwise
    searches in all open buffers
    - Fields:
      - `All severity flags can be passed as `string` or `number` as per
        `:vim.lsp.protocol.DiagnosticSeverity:`
    - Default keymaps:
      - `<C-l>`: show autocompletion menu to prefilter your query with the
        diagnostic you want to see (i.e. `:warning:`)


    Parameters: ~
        {opts} (table)  options to pass to the picker

    Fields: ~
        {severity}       (string|number)  filter diagnostics by severity name
                                          (string) or id (number)
        {severity_limit} (string|number)  keep diagnostics equal or more
                                          severe wrt severity name (string) or
                                          id (number)
        {severity_bound} (string|number)  keep diagnostics equal or less
                                          severe wrt severity name (string) or
                                          id (number)
        {no_sign}        (bool)           hide LspDiagnosticSigns from Results
                                          (default is false)
        {line_width}     (number)         set length of diagnostic entry text
                                          in Results



================================================================================
                                                              *telescope.themes*

Themes are ways to combine several elements of styling together.

They are helpful for managing the several differnt UI aspects for telescope and
provide a simple interface for users to get a particular "style" of picker.

themes.get_dropdown()                                  *themes.get_dropdown()*
    Dropdown style theme.

    Usage:

        `local builtin = require('telescope.builtin')`
        `local themes = require('telescope.themes')`
        `builtin.find_files(themes.get_dropdown())`



themes.get_cursor()                                      *themes.get_cursor()*
    Cursor style theme.

    Usage:

        `local builtin = require('telescope.builtin')`
        `local themes = require('telescope.themes')`
        `builtin.lsp_code_actions(themes.get_cursor())`



themes.get_ivy()                                            *themes.get_ivy()*
    Ivy style theme.

    Usage:

        `local builtin = require('telescope.builtin')`
        `local themes = require('telescope.themes')`
        `builtin.find_files(themes.get_ivy())`




================================================================================
                                                              *telescope.layout*

Layout strategies are different functions to position telescope.

All layout strategies are functions with the following signature:

  function(picker, columns, lines, layout_config)
    -- Do some calculations here...
    return {
      preview = preview_configuration
      results = results_configuration,
      prompt = prompt_configuration,
    }
  end

  Parameters: ~
    - picker        : A Picker object. (docs coming soon)
    - columns       : (number) Columns in the vim window
    - lines         : (number) Lines in the vim window
    - layout_config : (table) The configuration values specific to the picker.


This means you can create your own layout strategy if you want! Just be aware
for now that we may change some APIs or interfaces, so they may break if you
create your own.

A good method for creating your own would be to copy one of the strategies that
most resembles what you want from
"./lua/telescope/pickers/layout_strategies.lua" in the telescope repo.


layout_strategies.horizontal()                *layout_strategies.horizontal()*
    Horizontal layout has two columns, one for the preview and one for the
    prompt and results.

    ┌──────────────────────────────────────────────────┐
    │                                                  │
    │    ┌───────────────────┐┌───────────────────┐    │
    │    │                   ││                   │    │
    │    │                   ││                   │    │
    │    │                   ││                   │    │
    │    │      Results      ││                   │    │
    │    │                   ││      Preview      │    │
    │    │                   ││                   │    │
    │    │                   ││                   │    │
    │    └───────────────────┘│                   │    │
    │    ┌───────────────────┐│                   │    │
    │    │      Prompt       ││                   │    │
    │    └───────────────────┘└───────────────────┘    │
    │                                                  │
    └──────────────────────────────────────────────────┘

    `picker.layout_config` shared options:
      - height:
        - How tall to make Telescope's entire layout
        - See |resolver.resolve_height()|
      - mirror: Flip the location of the results/prompt and preview windows
      - scroll_speed: The number of lines to scroll through the previewer
      - width:
        - How wide to make Telescope's entire layout
        - See |resolver.resolve_width()|

    `picker.layout_config` unique options:
      - preview_cutoff: When columns are less than this value, the preview will be disabled
      - preview_width:
        - Change the width of Telescope's preview window
        - See |resolver.resolve_width()|
      - prompt_position:
        - Where to place prompt window.
        - Available Values: 'bottom', 'top'


layout_strategies.center()                        *layout_strategies.center()*
    Centered layout with a combined block of the prompt and results aligned to
    the middle of the screen. The preview window is then placed in the
    remaining space above. Particularly useful for creating dropdown menus (see
    |telescope.themes| and |themes.get_dropdown()|`).

    ┌──────────────────────────────────────────────────┐
    │    ┌────────────────────────────────────────┐    │
    │    |                 Preview                |    │
    │    |                 Preview                |    │
    │    └────────────────────────────────────────┘    │
    │    ┌────────────────────────────────────────┐    │
    │    |                 Prompt                 |    │
    │    ├────────────────────────────────────────┤    │
    │    |                 Result                 |    │
    │    |                 Result                 |    │
    │    └────────────────────────────────────────┘    │
    │                                                  │
    │                                                  │
    │                                                  │
    │                                                  │
    └──────────────────────────────────────────────────┘

    `picker.layout_config` shared options:
      - height:
        - How tall to make Telescope's entire layout
        - See |resolver.resolve_height()|
      - mirror: Flip the location of the results/prompt and preview windows
      - scroll_speed: The number of lines to scroll through the previewer
      - width:
        - How wide to make Telescope's entire layout
        - See |resolver.resolve_width()|

    `picker.layout_config` unique options:
      - preview_cutoff: When lines are less than this value, the preview will be disabled


layout_strategies.cursor()                        *layout_strategies.cursor()*
    Cursor layout dynamically positioned below the cursor if possible. If there
    is no place below the cursor it will be placed above.

    ┌──────────────────────────────────────────────────┐
    │                                                  │
    │   █                                              │
    │   ┌──────────────┐┌─────────────────────┐        │
    │   │    Prompt    ││      Preview        │        │
    │   ├──────────────┤│      Preview        │        │
    │   │    Result    ││      Preview        │        │
    │   │    Result    ││      Preview        │        │
    │   └──────────────┘└─────────────────────┘        │
    │                                         █        │
    │                                                  │
    │                                                  │
    │                                                  │
    │                                                  │
    │                                                  │
    └──────────────────────────────────────────────────┘



layout_strategies.vertical()                    *layout_strategies.vertical()*
    Vertical layout stacks the items on top of each other. Particularly useful
    with thinner windows.

    ┌──────────────────────────────────────────────────┐
    │                                                  │
    │    ┌────────────────────────────────────────┐    │
    │    |                 Preview                |    │
    │    |                 Preview                |    │
    │    |                 Preview                |    │
    │    └────────────────────────────────────────┘    │
    │    ┌────────────────────────────────────────┐    │
    │    |                 Result                 |    │
    │    |                 Result                 |    │
    │    └────────────────────────────────────────┘    │
    │    ┌────────────────────────────────────────┐    │
    │    |                 Prompt                 |    │
    │    └────────────────────────────────────────┘    │
    │                                                  │
    └──────────────────────────────────────────────────┘

    `picker.layout_config` shared options:
      - height:
        - How tall to make Telescope's entire layout
        - See |resolver.resolve_height()|
      - mirror: Flip the location of the results/prompt and preview windows
      - scroll_speed: The number of lines to scroll through the previewer
      - width:
        - How wide to make Telescope's entire layout
        - See |resolver.resolve_width()|

    `picker.layout_config` unique options:
      - preview_cutoff: When lines are less than this value, the preview will be disabled
      - preview_height:
        - Change the height of Telescope's preview window
        - See |resolver.resolve_height()|
      - prompt_position:
        - (unimplemented, but we plan on supporting)


layout_strategies.flex()                            *layout_strategies.flex()*
    Flex layout swaps between `horizontal` and `vertical` strategies based on
    the window width
     - Supports |layout_strategies.vertical| or |layout_strategies.horizontal|
       features


    `picker.layout_config` shared options:
      - height:
        - How tall to make Telescope's entire layout
        - See |resolver.resolve_height()|
      - mirror: Flip the location of the results/prompt and preview windows
      - scroll_speed: The number of lines to scroll through the previewer
      - width:
        - How wide to make Telescope's entire layout
        - See |resolver.resolve_width()|

    `picker.layout_config` unique options:
      - flip_columns: The number of columns required to move to horizontal mode
      - flip_lines: The number of lines required to move to horizontal mode
      - horizontal: Options to pass when switching to horizontal layout
      - vertical: Options to pass when switching to vertical layout


layout_strategies.bottom_pane()              *layout_strategies.bottom_pane()*
    Bottom pane can be used to create layouts similar to "ivy".

    For an easy ivy configuration, see |themes.get_ivy()|




================================================================================
                                                             *telescope.resolve*

Provides "resolver functions" to allow more customisable inputs for options.

resolver.resolve_height()                          *resolver.resolve_height()*
    Converts input to a function that returns the height. The input must take
    one of four forms:
    1. 0 <= number < 1
       This means total height as a percentage.
    2. 1 <= number
       This means total height as a fixed number.
    3. function
       Must have signature: function(self, max_columns, max_lines): number
    4. table of the form: {padding = `foo`}
       where `foo` has one of the previous three forms.
       The height is then set to be the remaining space after padding. For
       example, if the window has height 50, and the input is {padding = 5}, 
       the height returned will be `40 = 50 - 2*5`

    The returned function will have signature: function(self, max_columns,
    max_lines): number



resolver.resolve_width()                            *resolver.resolve_width()*
    Converts input to a function that returns the width. The input must take
    one of four forms:
    1. 0 <= number < 1
       This means total width as a percentage.
    2. 1 <= number
       This means total width as a fixed number.
    3. function
       Must have signature: function(self, max_columns, max_lines): number
    4. table of the form: {padding = `foo`}
       where `foo` has one of the previous three forms.
       The width is then set to be the remaining space after padding. For
       example, if the window has width 100, and the input is {padding = 5}, 
       the width returned will be `90 = 100 - 2*5`

    The returned function will have signature: function(self, max_columns,
    max_lines): number




================================================================================
                                                             *telescope.actions*

Actions functions that are useful for people creating their own mappings.

actions.move_selection_next({prompt_bufnr})    *actions.move_selection_next()*
    Move the selection to the next entry


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.move_selection_previous({prompt_bufnr})*actions.move_selection_previous()*
    Move the selection to the previous entry


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.move_selection_worse({prompt_bufnr})  *actions.move_selection_worse()*
    Move the selection to the entry that has a worse score


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.move_selection_better({prompt_bufnr})*actions.move_selection_better()*
    Move the selection to the entry that has a better score


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.move_to_top({prompt_bufnr})                    *actions.move_to_top()*
    Move to the top of the picker


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.move_to_middle({prompt_bufnr})              *actions.move_to_middle()*
    Move to the middle of the picker


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.move_to_bottom({prompt_bufnr})              *actions.move_to_bottom()*
    Move to the bottom of the picker


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.add_selection({prompt_bufnr})                *actions.add_selection()*
    Add current entry to multi select


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.remove_selection({prompt_bufnr})          *actions.remove_selection()*
    Remove current entry from multi select


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.toggle_selection({prompt_bufnr})          *actions.toggle_selection()*
    Toggle current entry status for multi select


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.select_all({prompt_bufnr})                      *actions.select_all()*
    Multi select all entries.
    - Note: selected entries may include results not visible in the results
      popup.


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.drop_all({prompt_bufnr})                          *actions.drop_all()*
    Drop all entries from the current multi selection.


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.toggle_all({prompt_bufnr})                      *actions.toggle_all()*
    Toggle multi selection for all entries.
    - Note: toggled entries may include results not visible in the results
      popup.


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.git_create_branch({prompt_bufnr})        *actions.git_create_branch()*
    Create and checkout a new git branch if it doesn't already exist


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.git_apply_stash({prompt_bufnr})            *actions.git_apply_stash()*
    Applies an existing git stash


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.git_checkout({prompt_bufnr})                  *actions.git_checkout()*
    Checkout an existing git branch


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.git_switch_branch({prompt_bufnr})        *actions.git_switch_branch()*
    Switch to git branch.
    If the branch already exists in local, switch to that. If the branch is
    only in remote, create new branch tracking remote and switch to new one.


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.git_track_branch({prompt_bufnr})          *actions.git_track_branch()*
    Tell git to track the currently selected remote branch in Telescope


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.git_delete_branch({prompt_bufnr})        *actions.git_delete_branch()*
    Delete the currently selected branch


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.git_merge_branch({prompt_bufnr})          *actions.git_merge_branch()*
    Merge the currently selected branch


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.git_rebase_branch({prompt_bufnr})        *actions.git_rebase_branch()*
    Rebase to selected git branch


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.git_reset_mixed({prompt_bufnr})            *actions.git_reset_mixed()*
    Reset to selected git commit using mixed mode


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.git_reset_soft({prompt_bufnr})              *actions.git_reset_soft()*
    Reset to selected git commit using soft mode


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.git_reset_hard({prompt_bufnr})              *actions.git_reset_hard()*
    Reset to selected git commit using hard mode


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.git_staging_toggle({prompt_bufnr})      *actions.git_staging_toggle()*
    Stage/unstage selected file


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.send_selected_to_qflist()          *actions.send_selected_to_qflist()*
    Sends the selected entries to the quickfix list, replacing the previous
    entries.



actions.add_selected_to_qflist()            *actions.add_selected_to_qflist()*
    Adds the selected entries to the quickfix list, keeping the previous
    entries.



actions.send_to_qflist()                            *actions.send_to_qflist()*
    Sends all entries to the quickfix list, replacing the previous entries.



actions.add_to_qflist()                              *actions.add_to_qflist()*
    Adds all entries to the quickfix list, keeping the previous entries.



actions.send_selected_to_loclist()        *actions.send_selected_to_loclist()*
    Sends the selected entries to the location list, replacing the previous
    entries.



actions.add_selected_to_loclist()          *actions.add_selected_to_loclist()*
    Adds the selected entries to the location list, keeping the previous
    entries.



actions.send_to_loclist()                          *actions.send_to_loclist()*
    Sends all entries to the location list, replacing the previous entries.



actions.add_to_loclist()                            *actions.add_to_loclist()*
    Adds all entries to the location list, keeping the previous entries.



actions.smart_send_to_qflist()                *actions.smart_send_to_qflist()*
    Sends the selected entries to the quickfix list, replacing the previous
    entries. If no entry was selected, sends all entries.



actions.smart_add_to_qflist()                  *actions.smart_add_to_qflist()*
    Adds the selected entries to the quickfix list, keeping the previous
    entries. If no entry was selected, adds all entries.



actions.smart_send_to_loclist()              *actions.smart_send_to_loclist()*
    Sends the selected entries to the location list, replacing the previous
    entries. If no entry was selected, sends all entries.



actions.smart_add_to_loclist()                *actions.smart_add_to_loclist()*
    Adds the selected entries to the location list, keeping the previous
    entries. If no entry was selected, adds all entries.



actions.open_qflist()                                  *actions.open_qflist()*
    Open the quickfix list



actions.open_loclist()                                *actions.open_loclist()*
    Open the location list



actions.delete_buffer({prompt_bufnr})                *actions.delete_buffer()*
    Delete the selected buffer or all the buffers selected using multi
    selection.


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.cycle_previewers_next({prompt_bufnr})*actions.cycle_previewers_next()*
    Cycle to the next previewer if there is one available.
    This action is not mapped on default.


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.cycle_previewers_prev({prompt_bufnr})*actions.cycle_previewers_prev()*
    Cycle to the previous previewer if there is one available.
    This action is not mapped on default.


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.remove_selected_picker({prompt_bufnr})*actions.remove_selected_picker()*
    Removes the selected picker in |builtin.pickers|.
    This action is not mapped by default and only intended for
    |builtin.pickers|.


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr


actions.which_key({prompt_bufnr})                        *actions.which_key()*
    Display the keymaps of registered actions similar to which-key.nvim.

    - Notes:
      - The defaults can be overridden via
        |action_generate.toggle_registered_actions|.


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr



================================================================================
                                                       *telescope.actions.state*

Functions to be used to determine the current state of telescope.

Generally used from within other |telescope.actions|

action_state.get_selected_entry()          *action_state.get_selected_entry()*
    Get the current entry



action_state.get_current_line()              *action_state.get_current_line()*
    Gets the current line



action_state.get_current_picker({prompt_bufnr})*action_state.get_current_picker()*
    Gets the current picker


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr



================================================================================
                                                         *telescope.actions.set*

Telescope action sets are used to provide an interface for managing actions
that all primarily do the same thing, but with slight tweaks.

For example, when editing files you may want it in the current split, a
vertical split, etc. Instead of making users have to overwrite EACH of those
every time they want to change this behavior, they can instead replace the
`set` itself and then it will work great and they're done.

action_set.shift_selection({prompt_bufnr}, {change})*action_set.shift_selection()*
    Move the current selection of a picker {change} rows. Handles not
    overflowing / underflowing the list.


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr
        {change}       (number)  The amount to shift the selection by


action_set.select({prompt_bufnr}, {type})                *action_set.select()*
    Select the current entry. This is the action set to overwrite common
    actions by the user.

    By default maps to editing a file.


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr
        {type}         (string)  The type of selection to make


action_set.edit({prompt_bufnr}, {command})                 *action_set.edit()*
    Edit a file based on the current selection.


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr
        {command}      (string)  The command to use to open the file.


action_set.scroll_previewer({prompt_bufnr}, {direction})*action_set.scroll_previewer()*
    Scrolls the previewer up or down


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr
        {direction}    (number)  The direction of the scrolling



================================================================================
                                                       *telescope.actions.utils*

Utilities to wrap functions around picker selections and entries.

Generally used from within other |telescope.actions|

utils.map_entries({prompt_bufnr}, {f})                   *utils.map_entries()*
    Apply `f` to the entries of the current picker.
    - Notes:
      - Mapped entries may include results not visible in the results popup.
      - Indices are 1-indexed, whereas rows are 0-indexed.
    - Warning: `map_entries` has no return value.
      - The below example showcases how to collect results
    Usage:
        local action_state = require "telescope.actions.state"
        local action_utils = require "telescope.actions.utils"
        function entry_value_by_row()
          local prompt_bufnr = vim.api.nvim_get_current_buf()
          local current_picker = action_state.get_current_picker(prompt_bufnr)
          local results = {}
            action_utils.map_entries(prompt_bufnr, function(entry, index, row)
            results[row] = entry.value
          end)
          return results
        end


    Parameters: ~
        {prompt_bufnr} (number)    The prompt bufnr
        {f}            (function)  Function to map onto entries of picker that
                                   takes (entry, index, row) as viable
                                   arguments


utils.map_selections({prompt_bufnr}, {f})             *utils.map_selections()*
    Apply `f` to the multi selections of the current picker and return a table
    of mapped selections.
    - Notes:
      - Mapped selections may include results not visible in the results popup.
      - Selected entries are returned in order of their selection.
    - Warning: `map_selections` has no return value.
      - The below example showcases how to collect results
    Usage:
        local action_state = require "telescope.actions.state"
        local action_utils = require "telescope.actions.utils"
        function selection_by_index()
          local prompt_bufnr = vim.api.nvim_get_current_buf()
          local current_picker = action_state.get_current_picker(prompt_bufnr)
          local results = {}
            action_utils.map_selections(prompt_bufnr, function(entry, index)
            results[index] = entry.value
          end)
          return results
        end


    Parameters: ~
        {prompt_bufnr} (number)    The prompt bufnr
        {f}            (function)  Function to map onto selection of picker
                                   that takes (selection) as a viable argument


utils.get_registered_mappings({prompt_bufnr})*utils.get_registered_mappings()*
    Utility to collect mappings of prompt buffer in array of `{mode, keybind,
    name}`.


    Parameters: ~
        {prompt_bufnr} (number)  The prompt bufnr



================================================================================
                                                    *telescope.actions.generate*

Module for convenience to override defaults of corresponding
|telescope.actions| at |telescope.setup()|.

General usage:
  require("telescope").setup {
    defaults = {
      mappings = {
        n = {
          ["?"] = action_generate.toggle_registered_actions {
            name_width = 20, -- typically leads to smaller floats
            max_height = 0.5, -- increase potential maximum height
            seperator = " > ", -- change sep between mode, keybind, and name
            close_with_action = false, -- do not close float on action
          },
        },
      },
    },
  }

action_generate.which_key({opts})                *action_generate.which_key()*
    Display the keymaps of registered actions similar to which-key.nvim.

    - Floating window:
      - Appears on the opposite side of the prompt.
      - Resolves to minimum required number of lines to show hints with `opts`
        or truncates entries at `max_height`.
      - Closes automatically on action call and can be disabled with by setting
        `close_with_action` to false.


    Parameters: ~
        {opts} (table)  options to pass to toggling registered actions

    Fields: ~
        {max_height}             (number)   % of max. height or no. of rows
                                            for hints (default: 0.4), see
                                            |resolver.resolve_height()|
        {only_show_current_mode} (boolean)  only show keymaps for the current
                                            mode (default: true)
        {mode_width}             (number)   fixed width of mode to be shown
                                            (default: 1)
        {keybind_width}          (number)   fixed width of keybind to be shown
                                            (default: 7)
        {name_width}             (number)   fixed width of action name to be
                                            shown (default: 30)
        {column_padding}         (string)   string to split; can be used for
                                            vertical seperator (default: " ")
        {mode_hl}                (string)   hl group of mode (default:
                                            TelescopeResultsConstant)
        {keybind_hl}             (string)   hl group of keybind (default:
                                            TelescopeResultsVariable)
        {name_hl}                (string)   hl group of action name (default:
                                            TelescopeResultsFunction)
        {column_indent}          (number)   number of left-most spaces before
                                            keybinds are shown (default: 4)
        {line_padding}           (number)   row padding in top and bottom of
                                            float (default: 1)
        {separator}              (string)   seperator string between mode, key
                                            bindings, and action (default: "
                                            -> ")
        {close_with_action}      (boolean)  registered action will close
                                            keymap float (default: true)
        {normal_hl}              (string)   winhl of "Normal" for keymap hints
                                            floating window (default:
                                            "TelescopePrompt")
        {border_hl}              (string)   winhl of "Normal" for keymap
                                            borders (default:
                                            "TelescopePromptBorder")
        {winblend}               (number)   pseudo-transparency of keymap
                                            hints floating window



================================================================================
                                                          *telescope.previewers*

Provides a Previewer table that has to be implemented by each previewer. To
achieve this, this module also provides two wrappers that abstract most of the
work and make it really easy create new previewers.
  - `previewers.new_termopen_previewer`
  - `previewers.new_buffer_previewer`

Furthermore, there are a collection of previewers already defined which can be
used for every picker, as long as the entries of the picker provide the
necessary fields. The more important once are
  - `previewers.cat`
  - `previewers.vimgrep`
  - `previewers.qflist`
  - `previewers.vim_buffer_cat`
  - `previewers.vim_buffer_vimgrep`
  - `previewers.vim_buffer_qflist`

Previewers can be disabled for any builtin or custom picker by doing :Telescope
find_files previewer=false

previewers.Previewer()                                *previewers.Previewer()*
    This is the base table all previewers have to implement. It's possible to
    write a wrapper for this because most previewers need to have the same keys
    set. Examples of wrappers are:
      - `new_buffer_previewer`
      - `new_termopen_previewer`

    To create a new table do following:
      - `local new_previewer = Previewer:new(opts)`

    What `:new` expects is listed below

    The interface provides following set of functions. All of them, besides
    `new`, will be handled by telescope pickers.
    - `:new(opts)`
    - `:preview(entry, status)`
    - `:teardown()`
    - `:send_input(input)`
    - `:scroll_fn(direction)`

    `Previewer:new()` expects a table as input with following keys:
      - `setup` function(self): Will be called the first time preview will be 
        called.
      - `teardown` function(self): Will be called on cleanup.
      - `preview_fn` function(self, entry, status): Will be called each time a
        new entry was selected.
      - `title` function(self): Will return the static title of the previewer.
      - `dynamic_title` function(self, entry): Will return the dynamic title of
        the previewer. Will only be called when config value
        dynamic_preview_title is true.
      - `send_input` function(self, input): This is meant for 
        `termopen_previewer` and it can be used to send input to the terminal 
        application, like less.
      - `scroll_fn` function(self, direction): Used to make scrolling work.



previewers.new()                                            *previewers.new()*
    A shorthand for creating a new Previewer. The provided table will be
    forwarded to `Previewer:new(...)`



previewers.new_termopen_previewer()      *previewers.new_termopen_previewer()*
    Is a wrapper around Previewer and helps with creating a new
    `termopen_previewer`.

    It requires you to specify one table entry `get_command(entry, status)`.
    This `get_command` function has to return the terminal command that will be
    executed for each entry. Example:
      get_command = function(entry, status)
        return { 'bat', entry.path }
      end

    Additionally you can define:
    - `title` a static title for example "File Preview"
    - `dyn_title(self, entry)` a dynamic title function which gets called when
      config value `dynamic_preview_title = true`

    It's an easy way to get your first previewer going and it integrates well
    with `bat` and `less`. Providing out of the box scrolling if the command
    uses less.

    Furthermore, it will forward all `config.set_env` environment variables to
    that terminal process.

    While this interface is a good start, it was replaced with the way more
    flexible `buffer_previewer` and is now deprecated.



previewers.cat()                                            *previewers.cat()*
    Provides a `termopen_previewer` which has the ability to display files. It
    will always show the top of the file and has support for `bat`(prioritized)
    and `cat`. Each entry has to provide either the field `path` or `filename`
    in order to make this previewer work.

    The preferred way of using this previewer is like this
    `require('telescope.config').values.cat_previewer` This will respect user
    configuration and will use `buffer_previewers` in case it's configured that
    way.



previewers.vimgrep()                                    *previewers.vimgrep()*
    Provides a `termopen_previewer` which has the ability to display files at
    the provided line. It has support for `bat`(prioritized) and `cat`. Each
    entry has to provide either the field `path` or `filename` and a `lnum`
    field in order to make this previewer work.

    The preferred way of using this previewer is like this
    `require('telescope.config').values.grep_previewer` This will respect user
    configuration and will use `buffer_previewers` in case it's configured that
    way.



previewers.qflist()                                      *previewers.qflist()*
    Provides a `termopen_previewer` which has the ability to display files at
    the provided line or range. It has support for `bat`(prioritized) and
    `cat`. Each entry has to provide either the field `path` or `filename`,
    `lnum` and a `start` and `finish` range in order to make this previewer
    work.

    The preferred way of using this previewer is like this
    `require('telescope.config').values.qflist_previewer` This will respect
    user configuration and will use buffer previewers in case it's configured
    that way.



previewers.new_buffer_previewer()          *previewers.new_buffer_previewer()*
    An interface to instantiate a new `buffer_previewer`. That means that the
    content actually lives inside a vim buffer which enables us more control
    over the actual content. For example, we can use `vim.fn.search` to jump to
    a specific line or reuse buffers/already opened files more easily. This
    interface is more complex than `termopen_previewer` but offers more
    flexibility over your content. It was designed to display files but was
    extended to also display the output of terminal commands.

    In the following options, state table and general tips are mentioned to
    make your experience with this previewer more seamless.


    options:
      - `define_preview = function(self, entry, status)` (required) Is called
        for each selected entry, after each selection_move (up or down) and is
        meant to handle things like reading file, jump to line or attach a
        highlighter.
      - `setup = function(self)` (optional) Is called once at the beginning,
        before the preview for the first entry is displayed. You can return a
        table of vars that will be available in `self.state` in each
        `define_preview` call.
      - `teardown = function(self)` (optional) Will be called at the end, when
        the picker is being closed and is meant to cleanup everything that was
        allocated by the previewer. The `buffer_previewer` will automatically
        cleanup all created buffers. So you only need to handle things that
        were introduced by you.
      - `keep_last_buf = true` (optional) Will not delete the last selected
        buffer. This would allow you to reuse that buffer in the select action.
        For example, that buffer can be opened in a new split, rather than
        recreating that buffer in an action. To access the last buffer number: 
        `require('telescope.state').get_global_key("last_preview_bufnr")`
      - `get_buffer_by_name = function(self, entry)` Allows you to set a unique
        name for each buffer. This is used for caching purpose.
        `self.state.bufname` will be nil if the entry was never loaded or the
        unique name when it was loaded once. For example, useful if you have
        one file but multiple entries. This happens for grep and lsp builtins.
        So to make the cache work only load content if `self.state.bufname ~=
        entry.your_unique_key`
      - `title` a static title for example "File Preview"
      - `dyn_title(self, entry)` a dynamic title function which gets called 
        when config value `dynamic_preview_title = true`

    `self.state` table:
      - `self.state.bufnr` Is the current buffer number, in which you have to
        write the loaded content. Don't create a buffer yourself, otherwise
        it's not managed by the buffer_previewer interface and you will
        probably be better off writing your own interface.
      - self.state.winid Current window id. Useful if you want to set the
        cursor to a provided line number.
      - self.state.bufname Will return the current buffer name, if
        `get_buffer_by_name` is defined. nil will be returned if the entry was
        never loaded or when `get_buffer_by_name` is not set.

    Tips:
      - If you want to display content of a terminal job, use: 
        `require('telescope.previewers.utils').job_maker(cmd, bufnr, opts)`
          - `cmd` table: for example { 'git', 'diff', entry.value }
          - `bufnr` number: in which the content will be written
          - `opts` table: with following keys
            - `bufname` string: used for cache
            - `value` string: used for cache
            - `mode` string: either "insert" or "append". "insert" is default
            - `env` table: define environment variables. Example:
              - `{ ['PAGER'] = '', ['MANWIDTH'] = 50 }`
            - `cwd` string: define current working directory for job
            - `callback` function(bufnr, content): will be called when job is
              done. Content will be nil if job is already loaded. So you can do
              highlighting only the first time the previewer is created for
              that entry. Use the returned `bufnr` and not `self.state.bufnr`
              in callback, because state can already be changed at this point
              in time.
      - If you want to attach a highlighter use:
        - `require('telescope.previewers.utils').highlighter(bufnr, ft)`
          - This will prioritize tree sitter highlighting if available for 
            environment and language.
        - `require('telescope.previewers.utils').regex_highlighter(bufnr, ft)`
        - `require('telescope.previewers.utils').ts_highlighter(bufnr, ft)`
      - If you want to use `vim.fn.search` or similar you need to run it in 
        that specific buffer context. Do
          vim.api.nvim_buf_call(bufnr, function()
            -- for example `search` and `matchadd`
          end)
        to achieve that.
      - If you want to read a file into the buffer it's best to use 
        `buffer_previewer_maker`. But access this function with 
        `require('telescope.config').values.buffer_previewer_maker` because it
        can be redefined by users.



previewers.buffer_previewer_maker({filepath}, {bufnr}, {opts})*previewers.buffer_previewer_maker()*
    A universal way of reading a file into a buffer previewer. It handles async
    reading, cache, highlighting, displaying directories and provides a
    callback which can be used, to jump to a line in the buffer.


    Parameters: ~
        {filepath} (string)  String to the filepath, will be expanded
        {bufnr}    (number)  Where the content will be written
        {opts}     (table)   keys: `use_ft_detect`, `bufname` and `callback`


previewers.vim_buffer_cat()                      *previewers.vim_buffer_cat()*
    A previewer that is used to display a file. It uses the `buffer_previewer`
    interface and won't jump to the line. To integrate this one into your own
    picker make sure that the field `path` or `filename` is set for each entry.
    The preferred way of using this previewer is like this
    `require('telescope.config').values.file_previewer` This will respect user
    configuration and will use `termopen_previewer` in case it's configured
    that way.



previewers.vim_buffer_vimgrep()              *previewers.vim_buffer_vimgrep()*
    A previewer that is used to display a file and jump to the provided line.
    It uses the `buffer_previewer` interface. To integrate this one into your
    own picker make sure that the field `path` or `filename` and `lnum` is set
    in each entry. If the latter is not present, it will default to the first
    line. The preferred way of using this previewer is like this
    `require('telescope.config').values.grep_previewer` This will respect user
    configuration and will use `termopen_previewer` in case it's configured
    that way.



previewers.vim_buffer_qflist()                *previewers.vim_buffer_qflist()*
    Is the same as `vim_buffer_vimgrep` and only exist for consistency with
    `term_previewers`.

    The preferred way of using this previewer is like this
    `require('telescope.config').values.qflist_previewer` This will respect
    user configuration and will use `termopen_previewer` in case it's
    configured that way.



previewers.git_branch_log()                      *previewers.git_branch_log()*
    A previewer that shows a log of a branch as graph



previewers.git_stash_diff()                      *previewers.git_stash_diff()*
    A previewer that shows a diff of a stash



previewers.git_commit_diff_to_parent()*previewers.git_commit_diff_to_parent()*
    A previewer that shows a diff of a commit to a parent commit.
    The run command is `git --no-pager diff SHA^! -- $CURRENT_FILE`

    The current file part is optional. So is only uses it with bcommits.



previewers.git_commit_diff_to_head()    *previewers.git_commit_diff_to_head()*
    A previewer that shows a diff of a commit to head.
    The run command is `git --no-pager diff --cached $SHA -- $CURRENT_FILE`

    The current file part is optional. So is only uses it with bcommits.



previewers.git_commit_diff_as_was()      *previewers.git_commit_diff_as_was()*
    A previewer that shows a diff of a commit as it was.
    The run command is `git --no-pager show $SHA:$CURRENT_FILE` or `git
    --no-pager show $SHA`



previewers.git_commit_message()              *previewers.git_commit_message()*
    A previewer that shows the commit message of a diff.
    The run command is `git --no-pager log -n 1 $SHA`



previewers.git_file_diff()                        *previewers.git_file_diff()*
    A previewer that shows the current diff of a file. Used in git_status.
    The run command is `git --no-pager diff $FILE`



previewers.display_content()                    *previewers.display_content()*
    A deprecated way of displaying content more easily. Was written at a time,
    where the buffer_previewer interface wasn't present. Nowadays it's easier
    to just use this. We will keep it around for backwards compatibility
    because some extensions use it. It doesn't use cache or some other clever
    tricks.




================================================================================
                                                     *telescope.actions.history*

A base implementation of a prompt history that provides a simple history and
can be replaced with a custom implementation.

For example: We provide a extension for a smart history that uses sql.nvim to
map histories to metadata, like the calling picker or cwd.

So you have a history for:
- find_files project_1
- grep_string project_1
- live_grep project_1
- find_files project_2
- grep_string project_2
- live_grep project_2
- etc

See github.com/nvim-telescope/telescope-smart-history.nvim

histories.History()                                      *histories.History()*
    Manages prompt history


    Fields: ~
        {enabled} (boolean)  Will indicate if History is enabled or disabled
        {path}    (string)   Will point to the location of the history file
        {limit}   (string)   Will have the limit of the history. Can be nil,
                             if limit is disabled.
        {content} (table)    History table. Needs to be filled by your own
                             History implementation
        {index}   (number)   Used to keep track of the next or previous index.
                             Default is #content + 1


histories.History:new({opts})                        *histories.History:new()*
    Create a new History


    Parameters: ~
        {opts} (table)  Defines the behavior of History

    Fields: ~
        {init}    (function)  Will be called after handling configuration
                              (required)
        {append}  (function)  How to append a new prompt item (required)
        {reset}   (function)  What happens on reset. Will be called when
                              telescope closes (required)
        {pre_get} (function)  Will be called before a next or previous item
                              will be returned (optional)


histories.new()                                              *histories.new()*
    Shorthand to create a new history



histories.History:reset()                          *histories.History:reset()*
    Will reset the history index to the default initial state. Will happen
    after the picker closed



histories.History:append({line}, {picker}, {no_reset})*histories.History:append()*
    Append a new line to the history


    Parameters: ~
        {line}     (string)   current line that will be appended
        {picker}   (table)    the current picker object
        {no_reset} (boolean)  On default it will reset the state at the end.
                              If you don't want to do this set to true


histories.History:get_next({line}, {picker})    *histories.History:get_next()*
    Will return the next history item. Can be nil if there are no next items


    Parameters: ~
        {line}   (string)  the current line
        {picker} (table)   the current picker object

    Return: ~
        string: the next history item


histories.History:get_prev({line}, {picker})    *histories.History:get_prev()*
    Will return the previous history item. Can be nil if there are no previous
    items


    Parameters: ~
        {line}   (string)  the current line
        {picker} (table)   the current picker object

    Return: ~
        string: the previous history item


histories.get_simple_history()                *histories.get_simple_history()*
    A simple implementation of history.

    It will keep one unified history across all pickers.




 vim:tw=78:ts=8:ft=help:norl: