Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mangelozzi/rgflow.nvim
Help you get in the flow with ripgrep in Neovim
https://github.com/mangelozzi/rgflow.nvim
neovim nvim-lua ripgrep
Last synced: 2 months ago
JSON representation
Help you get in the flow with ripgrep in Neovim
- Host: GitHub
- URL: https://github.com/mangelozzi/rgflow.nvim
- Owner: mangelozzi
- Created: 2020-07-15T17:50:21.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2024-01-23T15:10:14.000Z (5 months ago)
- Last Synced: 2024-01-24T09:32:02.174Z (5 months ago)
- Topics: neovim, nvim-lua, ripgrep
- Language: Lua
- Homepage:
- Size: 120 KB
- Stars: 57
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Lists
- awesome-neovim - mangelozzi/rgflow.nvim - Quickly get RipGrep results into an editable Quickfix list, while learning RipGrep's CLI. (Search / PHP)
- awesome-stars - mangelozzi/rgflow.nvim - Help you get in the flow with ripgrep in Neovim (Lua)
- awesome-neovim - mangelozzi/rgflow.nvim - Quickly get RipGrep results into an editable Quickfix list, while learning RipGrep's CLI. (Search / Markdown and LaTeX)
- awesome-neovim - mangelozzi/rgflow.nvim - Quickly get RipGrep results into an editable Quickfix list, while learning RipGrep's CLI. (Search / Markdown and LaTeX)
README
# rgflow.nvim
Get in the flow with RipGrep.
The more you use this plugin, the better you become at using RipGrep from the CLI.
Not simply a wrapper which could be replaced by a few lines of config.
It's a very simple to use tool aspiring to the Unix philosophy.
3 second intro:
Showing more of the features:
## QuickStart Guide (TL;DR)
1. Ensure you have [RipGrep](https://github.com/BurntSushi/ripgrep) installed
2. Set your plugin manager to use `mangelozzi/nvim-rgflow.lua` and install the plugin.
3. Create a file for the configuration, e.g. `~/.config/nvim/after/plugin/rgflow.lua`
4. Paste in the minimal configuration code:
```lua
require('rgflow').setup(
{
-- Set the default rip grep flags and options for when running a search via
-- RgFlow. Once changed via the UI, the previous search flags are used for
-- each subsequent search (until Neovim restarts).
cmd_flags = "--smart-case --fixed-strings --ignore --max-columns 200",
-- Mappings to trigger RgFlow functions
default_trigger_mappings = true,
-- These mappings are only active when the RgFlow UI (panel) is open
default_ui_mappings = true,
-- QuickFix window only mapping
default_quickfix_mappings = true,
}
)
```
5. After restarting Neovim, press `rg` to open the RgFlow UI
6. Type in a search pattern and press ``
7. A search will run and populate the QuickFix window
8. Press `dd` to delete a QuickFix entry, or select a visual range and press `d`
9. Press `TAB` to mark a line and `` to unmark a line, a line can be marked more than once
If you like this plugin please give it a :star:!
Bonus note: Pressing `` when the UI panel is open provides autocomplete for the line you are on (rip grep flags/cwords/filepaths)
## Why
- Main purpose: Perform a [RipGrep](https://github.com/BurntSushi/ripgrep)
with interface that is very close to the CLI, yet intuitive, and place those
results in the QuickFix list
- The more you use this plugin, the better you should become at using
RipGrep from the CLI.
- Additional features:
- QuickFix:
- Delete results operator, e.g. `dd`, or `3dj` and friends
- Mark/unmark results operator, e.g. `` to mark a result (can be marked more than once),
and `` to unmark a result.
- The operators also have a visual range counter variants.
- RipGrep flags/options auto complete.
- Bring up RipGrep help in a buffer, so you can navigate/search it Vim style.
- Find search results asynchronously
- Populates the QuickFix windows in batches so it seems like it's none blocking.
- Highlights the search term, so even if `:noh` the search terms are still highlighted
- Even if used a regex as the search term
- You can set it's theme colours. However if you are someone you likes to
change color scheme a lot, if you use the defaults they will update to
some sane defaults based on the applied scheme.
- Searches are appended to your command history, so you can easily repeat previous searches
- E.g. `:`
- I can never remember include/exclude globs, this helps.
- Also has autocomplete for RipGrep flags/options with descriptions
- Tested on Linux and Windows
## Installation
Use your favourite plugin manager, e.g. with [Packer](https://github.com/wbthomason/packer.nvim):
```Lua
use("mangelozzi/nvim-rgflow.lua")
```
And then `:PackerSync` etc. to install it.
## Setup
- For a minimal config refer to the Quick start guide.
### `cmd_flags`
- The parameter of most interest is probably `cmd_flags`
- The default value is `cmd_flags = "--smart-case --fixed-strings --no-fixed-strings --no-ignore --ignore --max-columns 500"`
- The reason it contains opposing settings (e.g. `--no-ignore` vs `--ignore`), is because then one can quickly deletes options as required
- E.g. since the later option "wins", deleting `--ignore` will make the `--no-ignore` flag take effect
### Mappings
- By default RgFlow will not change your editors current behaviour or modify any mappings.
- You have to opt in to use the default mappings
Default Mappings
```lua
mappings = {
trigger = {
-- Normal mode maps
n = {
["rG"] = "open_blank", -- open UI - search pattern = blank
["rg"] = "open_cword", -- open UI - search pattern =
["rp"] = "open_paste", -- open UI - search pattern = First line of unnamed register as the search pattern
["ra"] = "open_again", -- open UI - search pattern = Previous search pattern
["rx"] = "abort", -- close UI / abort searching / abortadding results
["rc"] = "print_cmd", -- Print a version of last run rip grep that can be pasted into a shell
["r?"] = "print_status", -- Print info about the current state of rgflow (mostly useful for deving on rgflow)
},
-- Visual/select mode maps
x = {
["rg"] = "open_visual", -- open UI - search pattern = current visual selection
},
},
-- Mappings that are local only to the RgFlow UI
ui = {
-- Normal mode maps
n = {
[""] = "start", -- With the ui open, start a search with the current parameters
[""] = "close", -- With the ui open, discard and close the UI window
["?"] = "show_rg_help", -- Show the rg help in a floating window, which can be closed with q or or the usual
[""] = "nop", -- No operation
[""] = "nop", -- No operation
[""] = "nop", -- No operation
},
-- Insert mode maps i = {
[""] = "start", -- With the ui open, start a search with the current parameters (from insert mode)
[""] = "auto_complete", -- start autocomplete if PUM not visible, if visible use own hotkeys to select an option
[""] = "auto_complete", -- start autocomplete if PUM not visible, if visible use own hotkeys to select an option
[""] = "auto_complete", -- start autocomplete if PUM not visible, if visible use own hotkeys to select an option
},
},
-- Mapping that are local only to the QuickFix window
quickfix = {
-- Normal
n = {
["d"] = "qf_delete", -- QuickFix normal mode delete operator
["dd"] = "qf_delete_line", -- QuickFix delete a line from quickfix
[""] = "qf_mark", -- QuickFix mark a line in the quickfix
[""] = "qf_unmark", -- QuickFix unmark a line in the quickfix window
[""] = "nop", -- No operation
[""] = "nop", -- No operation - Probably don't want to switch to a buffer in the little quickfix window
[""] = "nop", -- No operation
},
-- Visual/select mode maps
x = {
["d"] = "qf_delete_visual", -- QuickFix visual mode delete operator
[""] = "qf_mark_visual", -- QuickFix visual mode mark operator
[""] = "qf_unmark_visual", -- QuickFix visual mode unmark operator
}
},
}
```
### Full configuration options
For the full list of configurable settings refer to [Default settings](https://github.com/mangelozzi/rgflow.nvim/blob/master/lua/rgflow/defaults.lua)
### Example Config
This is my personnel configuration:
```lua
require("rgflow").setup(
{
default_trigger_mappings = true,
default_ui_mappings = true,
default_quickfix_mappings = true,
-- WARNING !!! Glob for '-g *{*}' will not use .gitignore file: https://github.com/BurntSushi/ripgrep/issues/2252
cmd_flags = ("--smart-case -g *.{*,py} -g !*.{min.js,pyc} --fixed-strings --no-fixed-strings --no-ignore -M 500"
-- Exclude globs
.. " -g !**/.angular/"
.. " -g !**/node_modules/"
.. " -g !**/static/*/jsapp/"
.. " -g !**/static/*/wcapp/"
)
}
)
```
## Lua Commands
- If you wish to create your own mappings, the below functions are provided.
- None of these commands require args except `setup` and `search`, however `open` can take optional args.
| **Command** | **Description** |
|---------------------------------------|--------------------------------------------------------|
| `require('rgflow').setup(config)` | Setup the plugin with the provided config settings
| `require('rgflow').open` | Opens the UI with default arguments.
**Pattern** = blank
**Flags** = previous flags (or `cmd_flags` after startup)
**Path** = PWD
| `require('rgflow').open(pattern, flags, path, options)` | Open UI with specified args
e.g. `require('rgflow').open('foo', '--smart-case --ignore', '~/code/my_project')`
Refer to section `Open Options` below for more detail.
| `require('rgflow').open_blank` | Open UI with blank search pattern (insert mode).
| `require('rgflow').open_cword` | Open UI with current word as the search pattern.
| `require('rgflow').open_again` | Open UI with previous search pattern.
| `require('rgflow').open_paste` | Open UI with first line of unnamed register as pattern.
| `require('rgflow').open_visual` | Open UI with current visual selection as pattern.
| `require('rgflow').start` | Start searching with current UI parameters.
| `require('rgflow').close` | Close the current UI window.
| `require('rgflow').search(pattern, flag, path)` | Execute search immediately with specified args.
| `require('rgflow').abort` | Abort current operation (searching or adding results).
| `require('rgflow').show_rg_help` | Show `rg --help` content in a popup window.
| `require('rgflow').nop` | No operation, useful for disabling hotkeys.
| `require('rgflow').get_cmd` | Get last run rip grep command.
| `require('rgflow').print_cmd` | Print last run rip grep command.
| `require('rgflow').qf_apply_hl` | After removing lines from the QF list by some means outside of RgFlow (e.g. `:Cfilter` or `:Cfilter!` command), one can sync the highlighting positions again.
| `require('rgflow').qf_delete` | QuickFix normal mode delete operator.
| `require('rgflow').qf_delete_line` | Delete a line from QuickFix.
| `require('rgflow').qf_delete_visual` | QuickFix visual mode delete operator.
| `require('rgflow').qf_mark` | QuickFix mark a line in the QuickFix window.
| `require('rgflow').qf_mark_visual` | QuickFix visual mode mark operator.
| `require('rgflow').qf_unmark` | QuickFix unmark a line in the QuickFix window.
| `require('rgflow').qf_unmark_visual` | QuickFix visual mode unmark operator.
| `require('rgflow').auto_complete` | Auto complete based on input box context.
| `require('rgflow').print_status` | Print info about the current state of rgflow.
### Open Options
- The open function signature looks like this:
- `require('rgflow').open(pattern, flags, path, options)`
- The `options` parameter is a lua table with the following keys (for now only one key):
- `custom_start`
- Useful for using Rgflow's UI to gather the search info, then call one's own tool.
- The parameter is a function that receives the pattern/flags/path (3 x strings) from UI, and performs it's own custom function, e.g. within a keymap:
```lua
vim.keymap.set("n", "RG", function()
-- Here we open UI with the default pattern/flags/path by passing in nil, nil, nil
require('rgflow').open(nil, nil, nil, {
custom_start = function(pattern, flags, path)
print('Pattern:'..pattern..' Flags:'..flags..' Path:'..path)
end
})
end, {noremap = true})
```
## Bonus Tips
- This plugin compliments `:Cfilter` very well.
- `:Cfilter` is built into Vim/Neovim for filtering your QuickFix lists.
- Although it comes with Neovim, it must first be enabled with: `vim.cmd('packadd cfilter')`
- `:Cfilter foo` will limit your QuickFix results to only those that contain the phrase `foo`
- `:Cfilter! foo` does the inverse, only those that **don't** contain `foo` are kept.
- By using `Cfilter` and this plugin's delete function, you can quickly massage your QuickFix list, making it ready to unleash a `:cdo` and `:cfdo` ... unlocking all sorts of super powers.
- e.g. To substitute the word `foo` for `bar` on each QuickFix match then save the modified file:
- `:cdo s/foo/bar/ | update`
## Contributing
PR's are welcome!
## License
Copyright (c) Michael Angelozzi. Distributed under the same terms as Neovim
itself. See `:help license`.