GRAB(1) Manual Page

  • Home
  • Back

  • GRAB(1) General Commands Manual GRAB(1)

    grab, git grabsearch for patterns in files

    grab [-s | -z] [-bcfnU] pattern [file ...]

    grab -h


    git grab [-s | -z] [-bcnU] pattern [glob ...]

    git grab -h

    The grab utility searches for text in files corresponding to pattern and prints the corresponding matches to the standard output. Unlike the grep(1) utility, grab 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 Pattern Syntax.

    The git grab utility is identical to the grab utility in all ways except for two exceptions. The first is that if no files (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 git-ls-files(1) are processed. If the user provides one or more globs, only the files returned by git-ls-files(1) that match one or more of the given globs will be processed. Secondly, the -f option is not available; its behavior is always assumed and cannot be disabled.

    grab 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 ‘-’ can also be provided, which represents the standard input.

    The default behavior of grab 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 -f and -z options.

    The options are as follows:

    , --byte-offset
    Report the positions of pattern matches using the byte offset/position in the file instead of the line and column.

    This option is useful if your text editor (such as vim(1) or emacs(1)) supports jumping directly to a given byte offset/position.

    , --color
    Force colored output, even if the output device is not a TTY. This is useful when piping the output of grab into a pager such as less(1).

    Even when this option is specified, if the TERM environment variable is set to ‘dumb’, no color will be output.

    , --filenames
    Always prefix matches with the names of the files in which the matches were made, even if only 1 file was provided.

    This option is always enabled when using git grab.

    , --help
    Display help information by opening this manual page.
    , --newline
    Treat the newline as a special character by disallowing the dot (‘.’) wildcard from matching newlines in regular expressions.

    This option may behave strangely when grab is not compiled with PCRE support. See CAVEATS for more information.

    , --strip-newline
    Don’t print a newline at the end of a match if the match already ends in a newline. This can make output seem more ‘natural’, as many matches will already have terminating newlines.

    This option is mutually exclusive with the -z option.

    , --no-unicode
    Don’t use Unicode properties when matching \d, \w, etc. Recognize only ASCII values instead.

    If grab is not compiled with PCRE support this option will cause the program to terminate with exit status 2.

    , --zero
    Separate output data by null bytes (‘\0’) instead of newlines. This option can be used to process matches containing newlines.

    If combined with the -f option, or if two or more files were provided as arguments, filenames and matches will be separated by null bytes instead of colons.

    This option is mutually exclusive with the -s option.

    By default grab supports Perl-compatible regular expressions (‘PCREs’), however it is possible to build and install grab without support for PCREs. When built without PCRE support, POSIX extended-regular-expressions are used instead.

    You should always assume that PCRE support is available, but if you would like to be absolutely sure you can check if the program terminates unsuccessfully when using the -U option.

    A pattern is a sequence 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.

    The supported operators are as follows:

    g
    Keep everything that matches the given regex.
    G
    Keep everything that doesn’t match the given regex.
    h
    Highlight everything that matches the given regex.
    H
    Highlight everything that doesn’t match the given regex.
    x
    Select everything that matches the given regex.
    X
    Select everything that doesn’t match the given regex.

    An example pattern to match all numbers that contain a ‘3’ but aren’t ‘1337’ could be ‘x/[0-9]+/ g/3/ G/^1337$/’. In that pattern, ‘x/[0-9]+/’ selects all numbers in the input, ‘g/3/’ keeps only those matches that contain the number 3, and ‘G/^1337$/’ filters out the specific number 1337.

    The delimiter used for each given operator can be any valid UTF-8 codepoint. As a result, the following pattern using the delimiters ‘|’, ‘.’, and ‘ä’ is well-formed:

    x|[0-9]+| g.3. Gä^1337ä

    Operators are not allowed to take empty regular expression arguments with one exception: ‘h’. When given an empty regular expression argument, the ‘h’ operator assumes the same regular expression as the previous operator. This allows you to avoid duplication in the common case where a user wishes to highlight text matched by a ‘g’ operator. The following example pattern selects all words that have a capital letter, and highlights the capital letter(s):

    x/\w+/ g/[A-Z]/ h//

    The empty ‘h’ operator is not permitted as the first operator in a pattern.

    A comma-separated list of color options in the form ‘key=val’. The value specified by val must be a SGR parameter. For more information see SEE ALSO.

    The keys are as follows:

    fn
    filenames prefixing any content line.
    hl
    text matched by an ‘h’ or ‘H’ command.
    ln
    line- and column-numbers, as well as byte offsets when reporting the location of a match.
    se
    separators inserted between filenames and content lines.

    The default value is ‘fn=35,hl=01;31,ln=32,se=36’

    Do not display any colored output when set to a non-empty string, even if the standard-output is a terminal.
    If set to ‘dumb’ disables colored output, even when the -c option is provided.

    The grab utility exits 0 on success, and >0 if an error occurs.

    List all your systems CPU flags, sorted and without duplicates:

    $ grab 'x/^flags.*/ x/\w+/ G/flags/' | sort | uniq

    Search for a pattern in multiple files without printing filenames:

    $ cat file1 file2 file3 | grab 'x/pattern/'

    Search for usages of an ‘<hb-form-text>’ Vue component — but only those which are being passed a ‘placeholder’ property — searching all files in the current git-repository:

    $ git grab 'x/<hb-form-text.*?>/ g/\bplaceholder\b/' '*.vue'

    Extract bibliographic references from mdoc(7) formatted manual pages:

    $ grab -n 'x/(^\.%.*\n)+/' foo.1 bar.1

    Extract the SYNOPSIS section from the given mdoc(7) formatted manual pages:

    $ grab -n 'x/^\.Sh SYNOPSIS\n(^.*\n(?!^\.Sh))+/' foo.1 bar.1

    git-ls-files(1), grep(1), pcre2syntax(3), regex(7)

    Rob Pike, Structural Regular Expressions, https://doc.cat-v.org/bell_labs/structural_regexps/se.pdf, 1987.

    SGR Parameters

    Thomas Voss <[email protected]>

    The behavior of negated character classes in regular expressions will vary when given the -n option depending on if PCRE support is or isn’t available.

    When PCRE support is available and the -n option is provided, the regular expression ‘[^a]’ will nonetheless match the newline character. When PCRE support is not available and the -n option is provided, the newline will be matched by ‘[^a]’.

    The pattern string provided as a command-line argument as well as the provided input files must be encoded as UTF-8. No other encodings are supported unless they are UTF-8 compatible, such as ASCII.

    23 January, 2024 Grab 2.1.1