README.md

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

• 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+