https://github.com/nvim-telescope/telescope-live-grep-args.nvim

Live grep with args
https://github.com/nvim-telescope/telescope-live-grep-args.nvim

Last synced: about 2 months ago
JSON representation

Live grep with args

• Host: GitHub
• URL: https://github.com/nvim-telescope/telescope-live-grep-args.nvim
• Owner: nvim-telescope
• Created: 2021-11-04T06:32:14.000Z (almost 3 years ago)
• Default Branch: master
• Last Pushed: 2024-07-28T08:29:52.000Z (about 2 months ago)
• Last Synced: 2024-07-28T09:42:54.542Z (about 2 months ago)
• Language: Lua
• Homepage:
• Size: 1.52 MB
• Stars: 647
• Watchers: 6
• Forks: 33
• Open Issues: 27
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSES/CC0-1.0.txt

Awesome Lists containing this project

README

        


# Telescope live grep args

[![REUSE status](https://api.reuse.software/badge/github.com/nvim-telescope/telescope-live-grep-args.nvim)](https://api.reuse.software/info/github.com/nvim-telescope/telescope-live-grep-args.nvim)

Live grep args picker for [telescope.nvim](https://github.com/nvim-telescope/telescope.nvim).

![](./img/telescope-live-grep-args.nvim.png)

## What it does

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

- `foo` → press `` → `"foo" ` → `"foo" -tmd`

  - Only works if you set up the `` mapping

- `--no-ignore foo`

- `"foo bar" bazdir`

- `"foo" --iglob **/bar/**`

Find the full [ripgrep guide](https://github.com/BurntSushi/ripgrep/blob/master/GUIDE.md) here to find out what is possible.

## Installation

[Changelog](./CHANGELOG.md)

    Lazy

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

```lua

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

    local telescope = require("telescope")

    -- first setup telescope

    telescope.setup({

        -- your config

    })

    -- then load the extension

    telescope.load_extension("live_grep_args")

  end

}

```

    Packer

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

```lua

use {

  "nvim-telescope/telescope.nvim",

  requires = {

    { "nvim-telescope/telescope-live-grep-args.nvim" },

  },

  config = function()

    local telescope = require("telescope")

    -- first setup telescope

    telescope.setup({

        -- your config

    })

    -- then load the extension

    telescope.load_extension("live_grep_args")

  end

}

```

    Other

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

```

local telescope = require("telescope")

-- first setup telescope

telescope.setup({

    -- your config

})

-- then load the extension

telescope.load_extension("live_grep_args")

```

## Setup

Map live grep args:

```

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

```

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

```lua

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 = {

          [""] = lga_actions.quote_prompt(),

          [""] = lga_actions.quote_prompt({ postfix = " --iglob " }),

          -- freeze the current list and start a fuzzy search in the frozen list

          [""] = actions.to_fuzzy_refine,

        },

      },

      -- ... also accepts theme settings, for example:

      -- theme = "dropdown", -- use dropdown theme

      -- theme = { }, -- use own theme spec

      -- layout_config = { mirror=true }, -- mirror preview pane

    }

  }

}

-- don't forget to load the extension

telescope.load_extension("live_grep_args")

```

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`.

`live_grep_args` args

| Name | Type | Description | Example |

| --- | --- | --- | --- |

| `additional_args` | `function|table` | additional arguments to be passed on. Can be fn(opts) -> tbl | `{ '-tmd' }` |

### 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", "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_word_under_cursor_current_buffer` | Same as `grep_word_under_cursor` but for the file of the current buffer | |

| `grep_visual_selection` | Start live grep with visual selection | see `grep_word_under_cursor` |

| `grep_word_visual_selection_current_buffer` | Same as `grep_visual_selection` but for the file of the current buffer | |


## Development

### Running the tests

- Clone [plenary.nvim](https://github.com/nvim-lua/plenary.nvim) next to this repo

- `make test`

## Acknowledgements

Based on the idea of this [pull request](https://github.com/nvim-telescope/telescope.nvim/pull/670).