nvim-telescope / telescope-live-grep-args.nvim

Live grep with args

Telescope live grep args

Live grep args picker for telescope.nvim.

What it does

It enables passing arguments to the grep command, rg examples:

• foo → press <C-k> → "foo" → "foo" -tmd
  • Only works if you set up the <C-k> mapping
• --no-ignore foo
• "foo bar" bazdir
• "foo" --iglob **/bar/**

Find the full ripgrep guide here to find out what is possible.

Installation

Changelog

Lazy

Add `telescope-live-grep-args.nvim` as `telescope.nvim` dependency, e.g.:

use {
  "nvim-telescope/telescope.nvim",
  dependencies = {
    { 
        "nvim-telescope/telescope-live-grep-args.nvim" ,
        -- This will not install any breaking changes.
        -- For major updates, this must be adjusted manually.
        version = "^1.0.0",
    },
  },
  config = function()
    require("telescope").load_extension("live_grep_args")
  end
}

Packer

Add `telescope-live-grep-args.nvim` as `telescope.nvim` dependency, e.g.:

use {
  "nvim-telescope/telescope.nvim",
  requires = {
    { "nvim-telescope/telescope-live-grep-args.nvim" },
  },
  config = function()
    require("telescope").load_extension("live_grep_args")
  end
}

Other

Once live grep args is available as lua module, load the extension:

require("telescope").load_extension("live_grep_args")

Setup

Map live grep args:

keymap.set("n", "<leader>fg", ":lua require('telescope').extensions.live_grep_args.live_grep_args()<CR>")

Call live grep args:

:lua require("telescope").extensions.live_grep_args.live_grep_args()

Usage

Options

Name	Description
search_dirs	Directory/directories/files to search. Paths are expanded and appended to the grep command.

Grep argument examples

(Some examples are ripgrep specific)

Prompt	Args	Description
foo bar	foo bar	search for „foo bar“
"foo bar" baz	foo bar, baz	search for „foo bar“ in dir „baz“
--no-ignore "foo bar	--no-ignore, foo bar	search for „foo bar“ ignoring ignores
"foo" --iglob **/test/**	search for „foo“ in any „test“ path
"foo" ../other-project	foo, ../other-project	search for „foo“ in ../other-project

If the prompt value does not begin with ', " or - the entire prompt is treated as a single argument. This behaviour can be turned off by setting the auto_quoting option to false.

Configuration

local telescope = require("telescope")
local lga_actions = require("telescope-live-grep-args.actions")

telescope.setup {
  extensions = {
    live_grep_args = {
      auto_quoting = true, -- enable/disable auto-quoting
      -- define mappings, e.g.
      mappings = { -- extend mappings
        i = {
          ["<C-k>"] = lga_actions.quote_prompt(),
          ["<C-i>"] = lga_actions.quote_prompt({ postfix = " --iglob " }),
        },
      },
      -- ... also accepts theme settings, for example:
      -- theme = "dropdown", -- use dropdown theme
      -- theme = { }, -- use own theme spec
      -- layout_config = { mirror=true }, -- mirror preview pane
    }
  }
}

This extension accepts the same options as builtin.live_grep, check out :help live_grep and :help vimgrep_arguments for more information. Additionally it also accepts theme and layout_config.

Mapping recipes:

This table provides some mapping ideas:

Mapped function	Description	Example
actions.quote_prompt()	Quote prompt	foo → "foo"
actions.quote_prompt({ postfix = ' --iglob ' })	Quote prompt and add --iglob	foo → "foo" --iglob
actions.quote_prompt({ postfix = ' -t' })	Quote prompt and add -t	foo → "foo" -t

Shortcut functions

Live grep args ships some additional shortcuts you can map.

This is an example to live grep for the word under the cursor:

local live_grep_args_shortcuts = require("telescope-live-grep-args.shortcuts")
keymap.set("n", "<leader>gc", live_grep_args_shortcuts.grep_word_under_cursor)

Available shortcuts:

Name	Action	Options
grep_word_under_cursor	Start live grep with word under cursor	postfix: postfix value to add; defaults to -F (Treat the pattern as a literal string) quote: Whether to quote the value; defaults to true trim: Whether to trim the value; defaults to true
grep_visual_selection	Start live grep with visual selection	see grep_word_under_cursor

Development

Running the tests

• Clone plenary.nvim next to this repo
• make test

Acknowledgements

Based on the idea of this pull request.