telescope-git-grep

Telescope Git Grep is a telescope extension that uses git grep to search tracked files.

Installation

You can install this plugin using your favorite vim package manager, eg. vim-plug, Packer or lazy.

Packer:

use({'davvid/telescope-git-grep.nvim'})

lazy:

{
    'davvid/telescope-git-grep.nvim'
}

vim-plug

Plug 'davvid/telescope-git-grep.nvim'

Usage

Activate the custom Telescope commands and git_grep extension by adding

require('telescope').load_extension('git_grep')

somewhere after your require('telescope').setup() call.

The following Telescope extension commands are provided:

" Perform a Live Grep
:Telescope git_grep

" Search for the current selection or the word under the cursor
:Telescope git_grep grep

" Perform a Live Grep
:Telescope git_grep live_grep

" Specify how "git grep" should interpret regex patterns.
:Telescope git_grep live_grep regex=perl

" Specify a custom repository path using the "cwd" option.
:Telescope git_grep live_grep cwd=~/path/to/repo

These commands can also be used from your init.lua.

For example, to bind git_grep to <leader>g and live_git_grep to <leader>G use:

-- Search for the current word and fuzzy-search over the result using git_grep.grep().
vim.keymap.set({'n', 'v'}, '<leader>g', function()
    require('git_grep').grep()
end)

-- Interactively search for a pattern using git_grep.live_grep().
vim.keymap.set('n', '<leader>G', function()
    require('git_grep').live_grep()
end)

Configuration

NOTE: You typically do not need to configure these fields. The following configuration fields are available if needed.

require('telescope').setup {
    extensions = {
        git_grep = {
            cwd = '%:h:p',
            regex = 'extended',
            skip_binary_files = false,
            use_git_root = true
        }
    }
}

The values shown above are the default values. You do not typically need to specify the git_grep = {...} extension configuration if the defaults work fine for you as-is.

You can also pass a { cwd = '...', use_git_root = true } table as the first argument directly to the extension functions to set these values at specific call sites. Only a subset of the fields must be specified.

As demonstrated in the :Telescope git_grep examples above, these fields can also be passed to the custom :Telescope git_grep {grep,live_grep} sub-commands using key=value expressions.

Regex Patterns

The regex field specifies how git interprets grep patterns. The following values are supported for regex.

extended - Use POSIX extended regular expressions for patterns. This is the default value.
basic - Use POSIX basic regular expressions for patterns.
fixed - Use fixed strings for patterns. Don't interpret pattern as a regex.
perl - Use Perl-compatible regular expressoins for patterns.

These values correspond to the --extended-regexp, --basic-regexp, --fixed-strings and --perl-regexp options, respectively. See git help grep for more details.

NOTE: git must be compiled with PCRE support in order to use perl regexes.

Git Root Directory

When use_git_root is enabled then the root of the Git repository will be detected and used as the current directory when launching git grep.

Setting use_git_root = false will launch git grep from the subdirectory containing the current file. This causes git grep to only search files within that directory.

Current Working Directory

The cwd field specifies the working directory to use when running git grep.

The default values of cwd = '%:h:p' and use_git_root = true make it so that git grep commands are launched from the root of the repository corresponding to current buffer's file. If the buffer is an anonymous buffer (with no filename) then nvim's current directory will be used.

Set cwd = '/some/repo' and set use_git_root = false if you want git grep to search in a specific directory.

Binary Files

Non-text binary files are searched by default. Set skip_binary_files = true to omit binary files from the grep results.

Development

The Garden file can be used to run lint checks using Garden.

# Run lint checks using "luacheck"
garden check

The documentation is generated using panvimdoc.

garden setup  # one-time setup
garden doc

Use garden fmt to apply code formatting using stylua.

The github repository is a mirror of the main repository on gitlab where you can file issues and submit merge requests.

Acknowledgements

telescope-git-grep was adapted from Telescope's internal telescope/builtin/__git.lua and telescope/builtin/__files.lua modules.