helm-rg
Search massive codebases extremely fast, using ripgrep
and helm
. Inspired by helm-ag
and f3
.
Also check out rg.el, which I haven't used much but seems pretty cool.
Usage
See the ripgrep
whirlwind tour for further information on invoking ripgrep
.
- Invoke the interactive function
helm-rg
to start a search with ripgrep
in the current directory.
helm
is used to browse the results and update the output as you type.
- Each line has the file path, the line number, and the column number of the start of the match, and each part is highlighted differently.
- Use TAB to invoke the helm persistent action, which previews the result and highlights the matched text in the preview.
- Use RET to visit the file containing the result, move point to the start of the match, and recenter.
- The result's buffer is displayed with
helm-rg-display-buffer-normal-method
(which defaults to switch-to-buffer
).
- Use a prefix argument (C-u RET) to open the buffer with
helm-rg-display-buffer-alternate-method
(which defaults to pop-to-buffer
).
- The text entered into the minibuffer is interpreted into a PCRE regexp to pass to
ripgrep
.
helm-rg
's pattern syntax is basically PCRE, but single spaces basically act as a more powerful conjunction operator.
- For example, the pattern
a b
in the minibuffer is transformed into a.*b|b.*a
.
- The single space can be used to find lines with any permutation of the regexps on either side of the space.
- Two spaces in a row will search for a literal single space.
ripgrep
's --smart-case
option is used so that case-sensitive search is only on if any of the characters in the pattern are capitalized.
- For example,
ab
(conceptually) searches [Aa][bB]
, but Ab
in the minibuffer will only search for the pattern Ab
with ripgrep
, because it has at least one uppercase letter.
- Use M-d to select a new directory to search from.
- Use M-g to input a glob pattern to filter files by, e.g.
*.py
.
- The glob pattern defaults to the value of
helm-rg-default-glob-string
, which is an empty string (matches every file) unless you customize it.
- Pressing M-g again shows the same minibuffer prompt for the glob pattern, with the string that was previously input.
- Use and to go up and down by files in the results.
- and simply go up and down by match result, and there may be many matches for your pattern in a single file, even multiple on a single line (which
ripgrep
reports as multiple separate results).
- The and keys will move up or down until it lands on a result from a different file than it started on.
- When moving by file,
helm-rg
will cycle around the results list, but it will print a harmless error message instead of looping infinitely if all results are from the same file.
- Use the interactive autoloaded function
helm-rg-display-help
to see the ripgrep command's usage info.
TODO
items checked completed here are ready to be added to the docs above
- [x] make a keybinding to drop into an "edit mode" and edit file content inline in results like
helm-ag
- currently called "bounce mode" in the alpha stage
- [x] needs to dedup results from the same line
- [x] should also merge the colorations
- [x] this might be easier without using the
--vimgrep
flag (!!!)
- [x] can insert markers on either side of each line to find the text added or removed
- [x] can change the filename by editing the file line
- [x] needs to reset all the file data for each entry if the file name is being changed!!!
- [x] can expand the windows of text beyond single lines at a time
- using
helm-rg--expand-match-context
and/or helm-rg--spread-match-context
- [x] and pop into another buffer for a quick view if you want
- can use
helm-rg--visit-current-file-for-bounce
- [ ] can expand up and down from file header lines to add lines from the top or bottom of the file!
- [ ] can use newlines in inserted text
- not for file names -- newlines are still removed there
- would need to use text properties to move by match results then, for everything that uses
helm-rg--apply-matches-with-file-for-bounce
basically
- [x] visiting the file should go to the appropriate line of the file!
- [ ] should flash a highlight of the matched text when visiting the file!
- [x] color all results in the file in the async action!
- [x] don't recolor when switching to a different result in the same file!
- [x] don't color matches whenever file path matches
helm-rg-shallow-highlight-files-regexp
- [ ] use
ripgrep
file types instead of flattening globbing out into helm-rg-default-glob-string
- user defines file types in a
defcustom
, and can interactively toggle the accepted file types
- user can also set the default set of file types
- as a dir-local variable!!
- [ ] add testing
- [ ] should be testing all of our interactive functions
- in all configurations (for all permutations of
defcustom
values)
- [ ] also everything that's called by helm
- does helm have any frameworks to make integration testing easier?
- [ ] publish
update-commentary.el
and the associated machinery
- as an npm package, MELPA package, pandoc writer, ???
- [ ] make a keybinding for running
helm-rg
on dired marked files
- then you could do an
f3
search, bounce to dired, then immediately helm-rg
on just the file paths from the f3
search, which would be sick
- [ ] does ripgrep have any options to traverse the fs in (any type of) sorted order?
- if so we'll definitely want a
defcustom
on that asap
License
GPL 3.0+