branch: externals/urgrep
commit fdd8dd54e67ce363b36fe84d058a8f6115ae197e
Author: Jim Porter <jporterb...@gmail.com>
Commit: Jim Porter <jporterb...@gmail.com>
Provide more details in the README
---
README.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++------
urgrep.el | 7 +++---
2 files changed, 77 insertions(+), 10 deletions(-)
diff --git a/README.md b/README.md
index 18b3e8c28e..8105880812 100644
--- a/README.md
+++ b/README.md
@@ -1,15 +1,81 @@
# Urgrep - Universal Recursive Grep
-Urgrep is an experimental Emacs package to provide an alternative to `M-x
rgrep`
-(and similar packages) which will eventually support for *any* grep-like tool.
-Currently, `ripgrep`, `ag`, `ack`, `git grep`, and `grep`/`find` are supported.
+**Urgrep** is an Emacs package to provide a universal frontend for *any*
+grep-like tool, as an alternative to the built-in `M-x rgrep` (and other
similar
+packages). Currently, `ripgrep`, `ag`, `ack`, `git grep`, and `grep`/`find` are
+supported.
+
+## Features
+
+#### One package, many tools
+
+No matter which tool you prefer, you can use it with Urgrep. If a new tool
comes
+along, you won't need to find a new Emacs package for it.
+
+#### Rich minibuffer interface
+
+Easily manipulate per-search options with Isearch-like key bindings within the
+Urgrep minibuffer prompt.
+
+#### Seamless support for TRAMP
+
+Each host can use a different set of tools depending on what the system has
+installed without any special configuration.
## Using Urgrep
-Load the package and type `C-h f urgrep RET`. That should show you the basics
-while the interface stabilizes (at which point it will be documented here).
+The primary entry point to Urgrep is the interactive function `urgrep`. This
+prompts you for a query to search for in, by default, the root directory of the
+current project (or the `default-directory` if there is no project). By
+prefixing with <kbd>C-u</kbd>, this will always start the search within the
+`default-directory`. With <kbd>C-u</kbd> <kbd>C-u</kbd>, Urgrep will allow you
+to enter the base directory. Within the search prompt, there are several
+Isearch-like key bindings to let you modify the search's behavior:
+
+| Key binding | Action |
+|:----------------------------|:-----------------------------------------|
+| <kbd>M-s</kbd> <kbd>r</kbd> | Toggle regexp search |
+| <kbd>M-s</kbd> <kbd>c</kbd> | Toggle case sensitivity |
+| <kbd>M-s</kbd> <kbd>f</kbd> | Set wildcards to filter files¹ |
+| <kbd>M-s</kbd> <kbd>C</kbd> | Set number of lines of context² |
+| <kbd>M-s</kbd> <kbd>B</kbd> | Set number of lines of leading context² |
+| <kbd>M-s</kbd> <kbd>A</kbd> | Set number of lines of trailing context² |
+
+> 1. Prompts with a recursive minibuffer<br>
+> 2. With a numeric prefix argument, set immediately; otherwise, use a
recursive
+> minibuffer
+
+In addition to the above, you can call `urgrep-run-command`, which works like
+`urgrep` but allows you to manually edit the command before executing it.
+
+### Configuring the tool to use
+
+By default, Urgrep tries all search tools it's aware of to find the best
option.
+To improve performance, you can restrict the set of tools to search for by
+setting `urgrep-preferred-tools`:
+
+```elisp
+(setq urgrep-preferred-tools '("git-grep" "grep"))
+```
+
+This also works with connection-local variables:
+
+```elisp
+(connection-local-set-profile-variables 'urgrep-ripgrep
+ '((urgrep-preferred-tools . ("ripgrep"))))
+
+(connection-local-set-profiles
+ '(:application tramp :machine "coco") 'urgrep-ripgrep)
+```
+
+## Programmatic interface
+
+In addition to interactive use, Urgrep is designed to allow for programmatic
+use, returning a command to execute with the specified query and options:
+`urgrep-command`. This takes a `query` as well as several optional keyword
+arguments. For more information, consult the docstring for `urgrep-command`.
## Contributing
-It's a bit early for other contributors, but thanks for the thought! (Hopefully
-this will change after not too long.)
+Feedback is welcome, but it's a bit early for code contributions. Thanks for
the
+thought, though! (Hopefully this will change after not too long.)
diff --git a/urgrep.el b/urgrep.el
index ef6f1f64bf..48374bc4ea 100644
--- a/urgrep.el
+++ b/urgrep.el
@@ -23,8 +23,9 @@
;;; Commentary:
-;; A universal frontend to various grep-like tools. Currently, ripgrep, ag,
-;; ack, git-grep, and grep are supported.
+;; A universal frontend to various grep-like tools. Currently, ripgrep, ag,
ack,
+;; git-grep, and grep are supported. The primary entry point to this package is
+;; the interactive function `urgrep' (which see).
;;; Code:
@@ -819,10 +820,10 @@ future searches."
(set-keymap-parent map minibuffer-local-map)
(define-key map "\M-sr" #'urgrep-toggle-regexp)
(define-key map "\M-sc" #'urgrep-toggle-case-fold)
+ (define-key map "\M-sf" #'urgrep-set-file-wildcards)
(define-key map "\M-sC" #'urgrep-set-context)
(define-key map "\M-sB" #'urgrep-set-before-context)
(define-key map "\M-sA" #'urgrep-set-after-context)
- (define-key map "\M-sf" #'urgrep-set-file-wildcards)
map))
(cl-defun urgrep--read-query (initial &key tool (group urgrep-group-matches)
