help.1

'\" t
.\" Automatically generated by Pandoc 3.1.3
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "fzf-search" "1" "Nov 2022" "Recursive search w/ FZF + RG" ""
.hy
.PP
Recursively search w/ FZF & Ripgrep
.SH Table of contents
.IP "1." 3
Usage (jump: \f[I]15g\f[R])
.IP "2." 3
Key bindings (jump: \f[I]35g\f[R])
.IP "3." 3
Ripgrep (Rust) Regex syntax (jump: \f[I]50g\f[R])
.IP "4." 3
FZF search syntax (jump: \f[I]243g\f[R])
.IP "5." 3
Upstream documentation (jump: \f[I]262g\f[R])
.SH Usage
.SS \f[V]fzf-search\f[R]
.IP
.nf
\f[C]
$ fzf-search [PATH...]
\f[R]
.fi
.PP
The default behaviour is to search the current directory.
The files are discovered by \f[V]rg\f[R], so you may customise file
discovery by using a Ripgrep configuration file.
You can set the \f[V]RIPGREP_CONFIG_PATH\f[R] environment variable to
specify the file.
To search multiple directories, you can provide the list of paths as
positional arguments.
.PP
Ripgrep is executed with the \f[V]--smart-case\f[R] option, which
implies a case insensitive search if the search query is all lower case,
but case sensitive otherwise.
.SS \f[V]fzf-file\f[R]
.IP
.nf
\f[C]
$ fzf-file [PATH...]
\f[R]
.fi
.PP
Same as above, the default behaviour to filter files is to discover
files in the current directory.
However to filter through files in multiple directories, you can provide
a list of paths as positional arguments.
Files are discovered using \f[V]rg --files\f[R].
.SS Piped usage
.IP
.nf
\f[C]
$ find <dir> -type d | QUERY=\[aq]foo bar\[aq] fzf-search
\f[R]
.fi
.PP
Both scripts can be invoked on a list of files piped through the
scripts.
You can specify the search query during invocation by setting the
\f[V]QUERY\f[R] environment variable to the query string.
.SH Key bindings
.TP
\f[B]F1\f[R]
this help message
.TP
\f[B]C-s\f[R]
recursive search - start a new search session with the current set of
files
.TP
\f[B]C-f\f[R]
filter current set of files
.TP
\f[B]RET\f[R]
view the current file in a pager
.TP
\f[B]M-RET\f[R]
open the current file with \f[V]$EDITOR\f[R]
.TP
\f[B]C-↑/↓\f[R]
scroll preview window up/down
.SH Ripgrep (Rust) regex syntax
.SS Matching one character
.PP
.TS
tab(@);
cw(12.0n) lw(58.0n).
T{
Character
T}@T{
Description
T}
_
T{
\f[V].\f[R]
T}@T{
any character except new line (includes new line with s flag)
T}
T{
\f[V]\[rs]d\f[R]
T}@T{
digit (\f[V]\[rs]p{Nd}\f[R])
T}
T{
\f[V]\[rs]D\f[R]
T}@T{
not digit
T}
T{
\f[V]\[rs]pN\f[R]
T}@T{
One-letter name Unicode character class
T}
T{
\f[V]\[rs]p{Greek}\f[R]
T}@T{
Unicode character class (general category or script)
T}
T{
\f[V]\[rs]PN\f[R]
T}@T{
Negated one-letter name Unicode character class
T}
T{
\f[V]\[rs]P{Greek}\f[R]
T}@T{
negated Unicode character class (general category or script)
T}
.TE
.SS Character classes
.PP
.TS
tab(@);
cw(14.2n) lw(55.8n).
T{
Character class
T}@T{
Description
T}
_
T{
\f[V][xyz]\f[R]
T}@T{
A character class matching either \f[V]x\f[R], \f[V]y\f[R] or
\f[V]z\f[R] (union).
T}
T{
\f[V][\[ha]xyz]\f[R]
T}@T{
A character class matching any character except \f[V]x\f[R], \f[V]y\f[R]
and \f[V]z\f[R].
T}
T{
\f[V][a-z]\f[R]
T}@T{
A character class matching any character in range \f[V]a-z\f[R].
T}
T{
\f[V][[:alpha:]]\f[R]
T}@T{
ASCII character class (\f[V][A-Za-z]\f[R])
T}
T{
\f[V][[:\[ha]alpha:]]\f[R]
T}@T{
Negated ASCII character class (\f[V][\[ha]A-Za-z]\f[R])
T}
T{
\f[V][x[\[ha]xyz]]\f[R]
T}@T{
Nested/grouping character class
T}
T{
T}@T{
(matching any character except \f[V]y\f[R] and \f[V]z\f[R])
T}
T{
\f[V][a-y&&xyz]\f[R]
T}@T{
Intersection (matching \f[V]x\f[R] or \f[V]y\f[R])
T}
T{
\f[V][0-9&&[\[ha]4]]\f[R]
T}@T{
Subtraction using intersection and negation
T}
T{
T}@T{
(matching \f[V]0-9\f[R] except \f[V]4\f[R])
T}
T{
\f[V][0-9--4]\f[R]
T}@T{
Direct subtraction (matching \f[V]0-9\f[R] except \f[V]4\f[R])
T}
T{
\f[V][a-g\[ti]\[ti]b-h]\f[R]
T}@T{
Symmetric difference (matching \f[V]a\f[R] and \f[V]h\f[R] only)
T}
T{
\f[V][\[rs][\[rs]]]\f[R]
T}@T{
Escaping in character classes (matching \f[V][\f[R] or \f[V]]\f[R])
T}
.TE
.PP
Any named character class may appear inside a bracketed \f[V][...]\f[R]
character class.
For example, \f[V][\[rs]p{Greek}[:digit:]]\f[R] matches any Greek or
ASCII digit.
\f[V][\[rs]p{Greek}&&\[rs]pL]\f[R] matches Greek letters.
Precedence in character classes, from most binding to least:
.IP "1." 3
Ranges: \f[V]a-cd\f[R] == \f[V][a-c]d\f[R]
.IP "2." 3
Union: \f[V]ab&&bc\f[R] == \f[V][ab]&&[bc]\f[R]
.IP "3." 3
Intersection: \f[V]\[ha]a-z&&b\f[R] == \f[V]\[ha][a-z&&b]\f[R]
.IP "4." 3
Negation
.SS Composites
.PP
.TS
tab(@);
c l.
T{
Composites
T}@T{
Description
T}
_
T{
\f[V]xy\f[R]
T}@T{
concatenation (\f[V]x\f[R] followed by \f[V]y\f[R])
T}
T{
\f[V]x|y\f[R]
T}@T{
alternation (\f[V]x\f[R] or \f[V]y\f[R], prefer \f[V]x\f[R])
T}
.TE
.SS Repetitions
.PP
.TS
tab(@);
c l.
T{
Repetitions
T}@T{
Description
T}
_
T{
\f[V]x*\f[R]
T}@T{
zero or more of \f[V]x\f[R] (greedy)
T}
T{
\f[V]x+\f[R]
T}@T{
one or more of \f[V]x\f[R] (greedy)
T}
T{
\f[V]x?\f[R]
T}@T{
zero or one of \f[V]x\f[R] (greedy)
T}
T{
\f[V]x*?\f[R]
T}@T{
zero or more of \f[V]x\f[R] (ungreedy/lazy)
T}
T{
\f[V]x+?\f[R]
T}@T{
one or more of \f[V]x\f[R] (ungreedy/lazy)
T}
T{
\f[V]x??\f[R]
T}@T{
zero or one of \f[V]x\f[R] (ungreedy/lazy)
T}
T{
\f[V]x{n,m}\f[R]
T}@T{
at least n \f[V]x\f[R] and at most m \f[V]x\f[R] (greedy)
T}
T{
\f[V]x{n,}\f[R]
T}@T{
at least n \f[V]x\f[R] (greedy)
T}
T{
\f[V]x{n}\f[R]
T}@T{
exactly n \f[V]x\f[R]
T}
T{
\f[V]x{n,m}?\f[R]
T}@T{
at least n \f[V]x\f[R] and at most m \f[V]x\f[R] (ungreedy/lazy)
T}
T{
\f[V]x{n,}?\f[R]
T}@T{
at least n \f[V]x\f[R] (ungreedy/lazy)
T}
T{
\f[V]x{n}?\f[R]
T}@T{
exactly n \f[V]x\f[R]
T}
.TE
.SS Empty matches
.PP
.TS
tab(@);
c l.
T{
Empty matches
T}@T{
Description
T}
_
T{
\f[V]\[ha]\f[R]
T}@T{
the beginning of text
T}
T{
T}@T{
(or start-of-line with multi-line mode)
T}
T{
\f[V]$\f[R]
T}@T{
the end of text
T}
T{
T}@T{
(or end-of-line with multi-line mode)
T}
T{
\f[V]\[rs]A\f[R]
T}@T{
only the beginning of text
T}
T{
T}@T{
(even with multi-line mode enabled)
T}
T{
\f[V]\[rs]z\f[R]
T}@T{
only the end of text
T}
T{
T}@T{
(even with multi-line mode enabled)
T}
T{
\f[V]\[rs]b\f[R]
T}@T{
a Unicode word boundary
T}
T{
T}@T{
(\f[V]\[rs]w\f[R] on one side and \f[V]\[rs]W\f[R], \f[V]\[rs]A\f[R], or
\f[V]\[rs]z\f[R] on other)
T}
T{
\f[V]\[rs]B\f[R]
T}@T{
not a Unicode word boundary
T}
.TE
.PP
The empty regex is valid and matches the empty string.
For example, the empty regex matches \f[V]abc\f[R] at positions
\f[V]0\f[R], \f[V]1\f[R], \f[V]2\f[R] and \f[V]3\f[R].
.SS Grouping and flags
.PP
.TS
tab(@);
c l.
T{
Groupings
T}@T{
Description
T}
_
T{
\f[V](exp)\f[R]
T}@T{
numbered capture group
T}
T{
T}@T{
(indexed by opening parenthesis)
T}
T{
\f[V](?P<name>exp)\f[R]
T}@T{
named (also numbered) capture group
T}
T{
T}@T{
(allowed chars: \f[V][_0-9a-zA-Z.\[rs][\[rs]]]\f[R])
T}
T{
\f[V](?:exp)\f[R]
T}@T{
non-capturing group
T}
T{
\f[V](?flags)\f[R]
T}@T{
set flags within current group
T}
T{
\f[V](?flags:exp)\f[R]
T}@T{
set flags for exp (non-capturing)
T}
.TE
.PP
Flags are each a single character.
For example, \f[V](?x)\f[R] sets the flag \f[V]x\f[R] and
\f[V](?-x)\f[R] clears the flag \f[V]x\f[R].
Multiple flags can be set or cleared at the same time: \f[V](?xy)\f[R]
sets both the \f[V]x\f[R] and \f[V]y\f[R] flags and \f[V](?x-y)\f[R]
sets the \f[V]x\f[R] flag and clears the \f[V]y\f[R] flag.
All flags are by default disabled unless stated otherwise.
They are:
.PP
.TS
tab(@);
cw(7.0n) lw(63.0n).
T{
Flags
T}@T{
Description
T}
_
T{
\f[V]i\f[R]
T}@T{
case-insensitive: letters match both upper and lower case
T}
T{
\f[V]m\f[R]
T}@T{
multi-line mode: \f[V]\[ha]\f[R] and \f[V]$\f[R] match begin/end of line
T}
T{
\f[V]s\f[R]
T}@T{
allow \f[V].\f[R] to match \f[V]\[rs]n\f[R]
T}
T{
\f[V]U\f[R]
T}@T{
swap the meaning of \f[V]x*\f[R] and \f[V]x*?\f[R]
T}
T{
\f[V]u\f[R]
T}@T{
Unicode support (enabled by default)
T}
T{
\f[V]x\f[R]
T}@T{
ignore whitespace and allow line comments (starting with \f[V]#\f[R])
T}
.TE
.PP
Flags can be toggled within a pattern.
Here\[cq]s an example that matches case-insensitively for the first part
but case-sensitively for the second part:
.IP
.nf
\f[C]
# use regex::Regex;
# fn main() {
let re = Regex::new(r\[dq](?i)a+(?-i)b+\[dq]).unwrap();
let cap = re.captures(\[dq]AaAaAbbBBBb\[dq]).unwrap();
assert_eq!(&cap[0], \[dq]AaAaAbb\[dq]);
# }
\f[R]
.fi
.PP
Notice that the \f[V]a+\f[R] matches either \f[V]a\f[R] or \f[V]A\f[R],
but the \f[V]b+\f[R] only matches \f[V]b\f[R].
Multi-line mode means \f[V]\[ha]\f[R] and \f[V]$\f[R] no longer match
just at the beginning/end of the input, but at the beginning/end of
lines:
.IP
.nf
\f[C]
# use regex::Regex;
let re = Regex::new(r\[dq](?m)\[ha]line \[rs]d+\[dq]).unwrap();
let m = re.find(\[dq]line one\[rs]nline 2\[rs]n\[dq]).unwrap();
assert_eq!(m.as_str(), \[dq]line 2\[dq]);
\f[R]
.fi
.PP
Note that \f[V]\[ha]\f[R] matches after new lines, even at the end of
input:
.IP
.nf
\f[C]
# use regex::Regex;
let re = Regex::new(r\[dq](?m)\[ha]\[dq]).unwrap();
let m = re.find_iter(\[dq]test\[rs]n\[dq]).last().unwrap();
assert_eq!((m.start(), m.end()), (5, 5));
\f[R]
.fi
.PP
Here is an example that uses an ASCII word boundary instead of a Unicode
word boundary:
.IP
.nf
\f[C]
# use regex::Regex;
# fn main() {
let re = Regex::new(r\[dq](?-u:\[rs]b).+(?-u:\[rs]b)\[dq]).unwrap();
let cap = re.captures(\[dq]$$abc$$\[dq]).unwrap();
assert_eq!(&cap[0], \[dq]abc\[dq]);
# }
\f[R]
.fi
.SS Escape sequences
.PP
.TS
tab(@);
cw(14.0n) lw(56.0n).
T{
Escape sequence
T}@T{
Description
T}
_
T{
\f[V]\[rs]*\f[R]
T}@T{
literal \f[V]*\f[R], works for any punctuation character:
\f[V]\[rs].+*?()|[]{}\[ha]$\f[R]
T}
T{
\f[V]\[rs]a\f[R]
T}@T{
bell (\f[V]\[rs]x07\f[R])
T}
T{
\f[V]\[rs]f\f[R]
T}@T{
form feed (\f[V]\[rs]x0C\f[R])
T}
T{
\f[V]\[rs]t\f[R]
T}@T{
horizontal tab
T}
T{
\f[V]\[rs]n\f[R]
T}@T{
new line
T}
T{
\f[V]\[rs]r\f[R]
T}@T{
carriage return
T}
T{
\f[V]\[rs]v\f[R]
T}@T{
vertical tab (\f[V]\[rs]x0B\f[R])
T}
T{
\f[V]\[rs]123\f[R]
T}@T{
octal character code (up to three digits) (when enabled)
T}
T{
\f[V]\[rs]x7F\f[R]
T}@T{
hex character code (exactly two digits)
T}
T{
\f[V]\[rs]x{10FFFF}\f[R]
T}@T{
any hex character code corresponding to a Unicode code point
T}
T{
\f[V]\[rs]u007F\f[R]
T}@T{
hex character code (exactly four digits)
T}
T{
\f[V]\[rs]u{7F}\f[R]
T}@T{
any hex character code corresponding to a Unicode code point
T}
T{
\f[V]\[rs]U0000007F\f[R]
T}@T{
hex character code (exactly eight digits)
T}
T{
\f[V]\[rs]U{7F}\f[R]
T}@T{
any hex character code corresponding to a Unicode code point
T}
.TE
.SS Perl character classes (Unicode friendly)
.PP
These classes are based on the definitions provided in
UTS#18 (https://www.unicode.org/reports/tr18/#Compatibility_Properties):
.PP
.TS
tab(@);
cw(17.0n) lw(53.0n).
T{
Character class
T}@T{
Description
T}
_
T{
\f[V]\[rs]d\f[R]
T}@T{
digit (\f[V]\[rs]p{Nd}\f[R])
T}
T{
\f[V]\[rs]D\f[R]
T}@T{
not digit
T}
T{
\f[V]\[rs]s\f[R]
T}@T{
whitespace (\f[V]\[rs]p{White_Space}\f[R])
T}
T{
\f[V]\[rs]S\f[R]
T}@T{
not whitespace
T}
T{
\f[V]\[rs]w\f[R]
T}@T{
word character
T}
T{
T}@T{
(\f[V]\[rs]p{Alphabetic}+\[rs]p{M}+\[rs]d+\[rs]p{Pc}+\[rs]p{Join_Control}\f[R])
T}
T{
\f[V]\[rs]W\f[R]
T}@T{
not word character
T}
.TE
.SS ASCII character classes
.PP
.TS
tab(@);
c l.
T{
Character class
T}@T{
Description
T}
_
T{
\f[V][[:alnum:]]\f[R]
T}@T{
alphanumeric (\f[V][0-9A-Za-z]\f[R])
T}
T{
\f[V][[:alpha:]]\f[R]
T}@T{
alphabetic (\f[V][A-Za-z]\f[R])
T}
T{
\f[V][[:ascii:]]\f[R]
T}@T{
ASCII (\f[V][\[rs]x00-\[rs]x7F]\f[R])
T}
T{
\f[V][[:blank:]]\f[R]
T}@T{
blank (\f[V][\[rs]t ]\f[R])
T}
T{
\f[V][[:cntrl:]]\f[R]
T}@T{
control (\f[V][\[rs]x00-\[rs]x1F\[rs]x7F]\f[R])
T}
T{
\f[V][[:digit:]]\f[R]
T}@T{
digits (\f[V][0-9]\f[R])
T}
T{
\f[V][[:graph:]]\f[R]
T}@T{
graphical (\f[V][!-\[ti]]\f[R])
T}
T{
\f[V][[:lower:]]\f[R]
T}@T{
lower case (\f[V][a-z]\f[R])
T}
T{
\f[V][[:print:]]\f[R]
T}@T{
printable (\f[V][ -\[ti]]\f[R])
T}
T{
\f[V][[:punct:]]\f[R]
T}@T{
punctuation (\f[V][!-/:-\[at]\[rs][-\[ga]\[ga]{-\[ti]]\f[R])
T}
T{
\f[V][[:space:]]\f[R]
T}@T{
whitespace (\f[V][\[rs]t\[rs]n\[rs]v\[rs]f\[rs]r ]\f[R])
T}
T{
\f[V][[:upper:]]\f[R]
T}@T{
upper case (\f[V][A-Z]\f[R])
T}
T{
\f[V][[:word:]]\f[R]
T}@T{
word characters (\f[V][0-9A-Za-z_]\f[R])
T}
T{
\f[V][[:xdigit:]]\f[R]
T}@T{
hex digit (\f[V][0-9A-Fa-f]\f[R])
T}
.TE
.SH FZF search syntax
.PP
Unless otherwise specified, fzf starts in \[lq]extended-search mode\[rq]
where you can type in multiple search terms delimited by spaces.
e.g.\ \f[V]\[ha]music .mp3$ sbtrkt !fire\f[R]
.PP
.TS
tab(@);
cw(10.0n) lw(25.5n) lw(34.5n).
T{
Token
T}@T{
Match type
T}@T{
Description
T}
_
T{
\f[V]sbtrkt\f[R]
T}@T{
fuzzy-match
T}@T{
Items that match \f[V]sbtrkt\f[R]
T}
T{
\f[V]\[aq]wild\f[R]
T}@T{
exact-match (quoted)
T}@T{
Items that include \f[V]wild\f[R]
T}
T{
\f[V]\[ha]music\f[R]
T}@T{
prefix-exact-match
T}@T{
Items that start with \f[V]music\f[R]
T}
T{
\f[V].mp3$\f[R]
T}@T{
suffix-exact-match
T}@T{
Items that end with \f[V].mp3\f[R]
T}
T{
\f[V]!fire\f[R]
T}@T{
inverse-exact-match
T}@T{
Items that do not include \f[V]fire\f[R]
T}
T{
\f[V]!\[ha]music\f[R]
T}@T{
inverse-prefix-exact-match
T}@T{
Items that do not start with \f[V]music\f[R]
T}
T{
\f[V]!.mp3$\f[R]
T}@T{
inverse-suffix-exact-match
T}@T{
Items that do not end with \f[V].mp3\f[R]
T}
.TE
.PP
If you don\[cq]t prefer fuzzy matching and do not wish to
\[lq]quote\[rq] every word, start fzf with \f[V]-e\f[R] or
\f[V]--exact\f[R] option.
Note that when \f[V]--exact\f[R] is set, \f[V]\[aq]\f[R]-prefix
\[lq]unquotes\[rq] the term.
.PP
A single bar character term acts as an OR operator.
For example, the following query matches entries that start with
\f[V]core\f[R] and end with either \f[V]go\f[R], \f[V]rb\f[R], or
\f[V]py\f[R].
.IP
.nf
\f[C]
\[ha]core go$ | rb$ | py$
\f[R]
.fi
.SH Upstream documentation
.PP
https://docs.rs/regex/latest/regex/index.html#syntax
.PP
https://github.com/junegunn/fzf/blob/master/README.md
.SH AUTHORS
Suvayu Ali.