Organize files into directories

2 files changed, 190 insertions, 0 deletions

diff --git a/man/git-grab.1 b/man/git-grab.1
new file mode 100644
index 0000000..64c35cc
--- /dev/null
+++ b/man/git-grab.1
@@ -0,0 +1 @@
+.so grab.1
diff --git a/man/grab.1 b/man/grab.1
new file mode 100644
index 0000000..8bd2e9e
--- /dev/null
+++ b/man/grab.1
@@ -0,0 +1,189 @@
+.Dd January 12 2024
+.Dt GRAB 1
+.Os
+.Sh NAME
+.Nm grab
+.Nd search for patterns in files
+.Sh SYNOPSIS
+.Nm
+.Op Fl fnz
+.Ar pattern
+.Op Ar
+.Nm
+.Fl h
+.Pp
+.Nm "git grab"
+.Op Fl nz
+.Ar pattern
+.Op Ar glob ...
+.Nm "git grab"
+.Fl h
+.Sh DESCRIPTION
+The
+.Nm
+utility searches for text in files corresponding to
+.Ar pattern
+and prints the corresponding matches to the standard output.
+Unlike the
+.Xr grep 1
+utility,
+.Nm
+is not strictly line-oriented;
+instead of always matching on complete lines,
+the user defines the structure of the text they would like to match and
+filters on the results.
+For more details on the pattern syntax, see
+.Sx Pattern Syntax .
+.Pp
+The
+.Nm git-grab
+utility is identical to the
+.Nm
+utility in all ways except for two exceptions.
+The first is that if no files
+.Pq globs in this case to be precise
+are specified,
+input is not read from the standard-input but instead all files returned
+by an invocation of
+.Xr git-ls-files 1
+are processed.
+If the user provides one or more globs,
+only the files returned by
+.Xr git-ls-files 1
+that match one or more of the given globs will be processed.
+Secondly, the
+.Fl f
+option is not available;
+its behavior is always assumed and cannot be disabled.
+.Pp
+.Nm
+will read from the files provided on the command-line.
+If no files are provided, the standard input will be read instead.
+The special filename
+.Sq -
+can also be provided,
+which represents the standard input.
+.Pp
+The default behavior of
+.Nm
+is to print pattern matches to the standard-output.
+If more than one file argument is provided,
+matches will be prefixed by their respective filename and a colon.
+Note that this behavior is modified by the
+.Fl f
+and
+.Fl z
+options.
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl f , Fl Fl filenames
+Always prefix matches with the names of the files in which the matches
+were made,
+even if only 1 file was provided.
+.It Fl h , Fl Fl help
+Display help information by opening this manual page.
+.It Fl n , Fl Fl newline
+Don’t match newline characters
+.Pq Sq \en
+with the dot
+.Pq Sq \&.
+operator in patterns,
+or in negated character-classes.
+.It Fl z , Fl Fl zero
+Separate output data by null bytes
+.Pq Sq \e0
+instead of newlines.
+This option can be used to process matches containing newlines.
+.Pp
+If combined with the
+.Fl f
+option,
+or if two or more files were provided as arguments,
+filenames and matches will be separated by null bytes instead of colons.
+.El
+.Ss Pattern Syntax
+A pattern is a sequences of commands optionally separated by whitespace.
+A command is an operator followed by a delimiter, a regular expression,
+and then terminated by the same delimiter.  The last command of a pattern
+need not have a terminating delimiter.
+.Pp
+The supported operators are as follows:
+.Bl -tag -compact
+.It g
+Keep selections that match the given regex.
+.It v
+Discard selections that match the given regex.
+.It x
+Select everything that matches the given regex.
+.It y
+Select everything that doesn’t match the given regex.
+.El
+.Pp
+An example pattern to match all numbers that contain a ‘3’ but aren’t
+‘1337’ could be
+.Sq x/[0-9]+/ g/3/ v/^1337$/ .
+In that pattern,
+.Sq x/[0-9]+/
+selects all numbers in the input,
+.Sq g/3/
+keeps only those matches that contain the number 3,
+and
+.Sq v/^1337$/
+filters out the specific number 1337.
+.Pp
+As you may use whichever delimiter you like, the following is also valid:
+.Pp
+.Dl x|[0-9]+| g.3. v#^1337#
+.Sh ENVIRONMENT
+.Bl -tag -width GRAB_COLOR_FNAME
+.It Ev GRAB_COLOR_FNAME
+The color(s) with which to highlight filenames,
+or 35 if unset.
+.It Ev GRAB_COLOR_SEPC
+The color(s) with which to highlight the colon-separator between
+filenames and matches,
+or 36 if unset.
+.It Ev NO_COLOR
+Do not display any colored output when set to a non-empty string,
+even if the standard-output is a terminal.
+.El
+.Pp
+The
+.Ev GRAB_COLOR_*
+environment variables are SGR parameters.
+For more information regarding SGR parameters see
+.Sx SEE ALSO .
+.Sh EXIT STATUS
+.Ex -std
+.Sh EXAMPLES
+List all your systems CPU flags, sorted and without duplicates:
+.Pp
+.Dl $ grab 'x/^flags.*/ x/\ew+/ v/flags/' | sort | uniq
+.Pp
+Search for a pattern in multiple files without printing filenames:
+.Pp
+.Dl $ cat file1 file2 file3 | grab 'x/pattern/'
+.Pp
+Search for usages of an
+.Ql <hb-form-text>
+Vue component —
+but only those which are being passed a
+.Ql placeholder
+property —
+searching all files in the current git-repository:
+.Pp
+.Dl $ git grab 'x/<hb-form-text[^>]+>/ g/\ebplaceholder\eb/' '*.vue'
+.Sh SEE ALSO
+.Xr git-ls-files 1 ,
+.Xr grep 1
+.Rs
+.%A Rob Pike
+.%D 1987
+.%T Structural Regular Expressions
+.%U https://doc.cat-v.org/bell_labs/structural_regexps/se.pdf
+.Re
+.Pp
+.Lk https://en.wikipedia.org/wiki/ANSI_escape_code#SGR "SGR Parameters"
+.Sh AUTHORS
+.An Thomas Voss Aq Mt mail@thomasvoss.com