From 294a41b736d059cf4b1faec4ee0375afe0257400 Mon Sep 17 00:00:00 2001 From: Laurence Withers Date: Fri, 7 Jul 2023 11:50:00 +0100 Subject: [PATCH] Flesh out README --- README.md | 43 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 42 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 1951b6c..bda317b 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,44 @@ # gg -Recursive grep written in Go, for everyday ease of use. \ No newline at end of file +Recursive grep written in Go, for everyday ease of use. + +`gg` is a recursive grep. Given a regexp (or fixed pattern) it will search for +the pattern recursively in the current working directory. It will print a +coloured header per file along with the matching line and pattern. + +It is possible to scan specific files or directories, rather than the default +current working directory. To do this, simply specify the path(s) as arguments +following the pattern. + +It is possible to scan for multiple patterns using the `-e` (or `-Q`) argument, +which can be repeated multiple times. `-e` specifies a regular expression and +`-Q` a fixed pattern. When using either flag, any non-flag arguments are treated +as paths to scan. + +Search defaults to case-sensitive but the `-i` flag may be passed to make all +search terms case-insensitive. Alternatively, the `"(?i)"` construct may be added +to a regular expression to make that specific expression case insensitive. + +Files and directories can be excluded with the `-x` option. This supports bash-style +globs with `'*'`, `'?'`, `'[a-z]'`, `'{this,that}'`, or `'/**/'` to match zero or more +directories. By default, `.git` and vim swap files are ignored. Similarly, `-I` +filters files to include. Examples: + +``` + # ignore files/dirs with .js or .css suffix + gg -x '*.js' -x '*.css' pattern + + # only match files with .go suffix (any subdir) + gg -I '*.go' pattern + + # only match files whose parent dir is "stuff", but ignore "foo" subdir + gg -x ./foo -I 'stuff/*' pattern + + # only match .js files with a directory "things" in the path, but ignore + # .min.js (e.g. will match "foo/things/bar/my.js") + gg -I 'things/**/*.js' -x '*.min.js' pattern +``` + +Symlinks named on the command line are followed, but by default symlinks are +not followed when recursing into directories. `-L` allows them to be +dereferenced.