/helm-rg

ripgrep is nice

Primary LanguageEmacs LispGNU General Public License v3.0GPL-3.0

helm-rg

MELPA

helm-rg example usage

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

  • 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
    • needs to dedup results from the same line
      • should also merge the colorations
      • this might be easier without using the --vimgrep flag (!!!)
    • can insert markers on either side of each line to find the text added or removed
    • can change the filename by editing the file line
      • needs to reset all the file data for each entry if the file name is being changed!!!
    • 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
      • 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
    • visiting the file should go to the appropriate line of the file!
      • should flash a highlight of the matched text when visiting the file!
  • color all results in the file in the async action!
    • don't recolor when switching to a different result in the same file!
    • 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+