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

" Search for the current selection or the word under the cursor across all worktrees in your session
:Telescope git_grep workspace_grep

" Perform a Live Grep across all worktrees in your session
:Telescope git_grep workspace_live_grep

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 in your current worktree
vim.keymap.set({'n', 'v'}, '<leader>g', function()
    require('git_grep').grep()
end)

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

-- Search for the current word across all workspaces in your current session
vim.keymap.set({'n', 'v'}, '<leader>g', function()
    require('git_grep').workspace_grep()
end)

-- Interactively search for a pattern across all worktrees in your current session
vim.keymap.set('n', '<leader>G', function()
    require('git_grep').workspace_live_grep()
end)

Workspace Grep Search

The worskpace_grep and workspace_live_grep commands operate over all of the worktrees in your current session. Your "current session" is defined as all of the buffers that you currently have open. These commands will find all of the git worktrees corresponding to your open buffers and performs searches over all of them in a single shot.

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 = nil,
            skip_binary_files = false,
            use_git_root = true,
            max_results = 10000,
            search_title = 'Git Grep',
        }
    }
}

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.
• 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. The default value comes from the git configuration grep.patternType. 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.

The use_git_root is ignored when using the worskpace grep commands.

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.

The cwd option is ignored when using the workspace grep commands.

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.