LinuxHandbook/article/linux-grep-tutorial.md at main · fhmio/LinuxHandbook

title

Linux Command Tutorial: grep

date

2026-09-12 00:00:00 +0000

1. Introduction

Upstream: GNU Grep 3.11 | POSIX: POSIX.1-2024 (with GNU extensions) | Safety Tier: safe-read-only | Scope: Fast pattern search, regex filtering & stream line extraction

grep searches input files for lines matching one or more regular expression patterns. It utilizes the Boyer-Moore fast string search algorithm alongside deterministic finite automata (DFA) regex engines, streaming matching lines to standard output.

Upstream Project & Provenance: Developed and maintained under GNU Grep (grep).
Portability & Standards Baseline: Standardized in IEEE Std 1003.1-2024 (POSIX.1-2024). GNU grep incorporates Perl-Compatible Regular Expressions (-P), context controls (-A, -B, -C), recursive directory searches (-r, -R), and color highlighting.
Target Research Implementation: Audited against GNU Grep 3.11 (grep(1)).
Applicability & Lifecycle: The standard text filtering utility for shell pipelines, log analysis, and source code navigation.

2. Syntax and Command Model

2.1 Canonical Synopsis

grep [OPTION...] PATTERNS [FILE...]
grep [OPTION...] -e PATTERNS ... [FILE...]
grep [OPTION...] -f PATTERN_FILE ... [FILE...]

2.2 Regular Expression Dialects

GNU grep supports four distinct regex matching engines:

Basic Regular Expressions (BRE, default or -G): Standard POSIX syntax; special characters like (, ), {, }, +, ? require backslash escaping to function as operators.
Extended Regular Expressions (ERE, -E or egrep): Metacharacters like (, ), {, }, +, ?, | are operators by default.
Fixed Strings (-F or fgrep): Treats patterns as exact literal strings; disables regex evaluation for maximum performance.
Perl-Compatible Regular Expressions (PCRE, -P): Full Perl 5 regex syntax, including lookaheads (?=...), lookbehinds (?<=...), non-greedy quantifiers .*?, and character classes \d, \s, \w.

3. Options

3.1 Matching and Selection Flags

Short Flag	Long Flag	Description	POSIX Defined
`-E`	`--extended-regexp`	Interpret PATTERNS as extended regular expressions (ERE).	Yes
`-F`	`--fixed-strings`	Interpret PATTERNS as fixed strings (no regex).	Yes
`-P`	`--perl-regexp`	Interpret PATTERNS as Perl-compatible regular expressions.	No
`-i`	`--ignore-case`	Ignore case distinctions in patterns and input data.	Yes
`-v`	`--invert-match`	Invert the sense of matching, to select non-matching lines.	Yes
`-w`	`--word-regexp`	Select only those lines containing matches that form whole words.	No
`-x`	`--line-regexp`	Select only those matches that exactly match the whole line.	Yes

3.2 Output Control and Formatting

Short Flag	Long Flag	Description	POSIX Defined
`-n`	`--line-number`	Prefix each line of output with the 1-based line number.	Yes
`-c`	`--count`	Suppress normal output; print a count of matching lines.	Yes
`-l`	`--files-with-matches`	Print only names of FILEs with matching lines.	Yes
`-L`	`--files-without-match`	Print only names of FILEs with no matching lines.	No
`-o`	`--only-matching`	Print only the matched (non-empty) parts of a matching line.	No
`-q`	`--quiet`, `--silent`	Quiet mode: suppress all output; exit immediately with 0 if match found.	Yes
`-r`	`--recursive`	Read all files under each directory recursively; follow symlinks only on command line.	No
`-R`	`--dereference-recursive`	Recursively search directories, following all symbolic links.	No

3.3 Context Line Controls

Short Flag	Long Flag	Description	Default
`-A NUM`	`--after-context=NUM`	Print NUM lines of trailing context after matching lines.	`0`
`-B NUM`	`--before-context=NUM`	Print NUM lines of leading context before matching lines.	`0`
`-C NUM`	`--context=NUM`	Print NUM lines of leading and trailing output context.	`0`

4. Basic Usage

4.1 Quick Reference & Common Invocations

Task / Scenario	Command	Key Flags / Behavior
Case-insensitive search	`grep -i "error" app.log`	`-i` matches upper and lower case
Show matching line numbers	`grep -n "listen" nginx.conf`	`-n` prefixes 1-based line numbers
Invert match (exclude lines)	`grep -v "^#" config.conf`	`-v` selects lines that do NOT match
Only print matched substring	`grep -E -o "[0-9]{1,3}\.[0-9]{1,3}..." log`	`-o` outputs matched token per line
Count matching lines	`grep -c "404" access.log`	`-c` prints count instead of lines
Fast literal search	`grep -F "192.168.1.1" access.log`	`-F` disables regex for maximum speed
Recursive search with line numbers	`grep -rn "API_KEY" ./src`	`-r` recursive search; `-n` line numbers
Show lines with context	`grep -B 2 -A 3 "FATAL" error.log`	`-B` before lines; `-A` after lines
Quiet check (for if statements)	`if grep -q "root" /etc/passwd; then ...`	`-q` exits 0 on first match, no output

4.2 Case-Insensitive Matching

grep -i "error" /var/log/nginx/error.log

4.3 Showing Line Numbers

grep -n "listen" /etc/nginx/nginx.conf

Sample terminal output:

38:        listen       80 default_server;
39:        listen       [::]:80 default_server;

5. Practical Operations

5.1 Extracting IP Addresses with `-o` and Extended Regex

Extracting only IPv4 addresses from an access log:

grep -E -o "([0-9]{1,3}\.){3}[0-9]{1,3}" /var/log/nginx/access.log | head -n 3

Sample terminal output:

192.168.1.45
10.0.0.12
172.16.5.99

Technical Analysis: -o strips everything else on the line, outputting each regex match on its own dedicated newline.

5.2 Contextual Inspection of Errors

Viewing 2 lines before and 3 lines after a database connection error:

grep -B 2 -A 3 "FATAL: connection refused" /var/log/postgresql/postgresql.log

Sample terminal output:

2026-09-12 11:20:00 [4123] LOG: starting background worker
2026-09-12 11:20:01 [4123] LOG: connecting to primary node
2026-09-12 11:20:02 [4123] FATAL: connection refused
2026-09-12 11:20:02 [4123] DETAIL: target server unreachable at port 5432
2026-09-12 11:20:02 [4123] LOG: worker process exited with code 1
2026-09-12 11:20:03 [4123] LOG: retrying in 5 seconds

5.3 Recursive Codebase Search Excluding Git Directories

grep -rn --exclude-dir=".git" --exclude-dir="node_modules" "API_KEY" ./src

Traverses ./src recursively, printing file names and line numbers while skipping bulky vendor and version control trees.

5.4 Fast Fixed-String Search Across Massive Files

When searching for exact strings (no regex metacharacters), -F achieves significantly higher throughput:

grep -F "user_id_482918" /data/event_stream.json

Bypasses regex compilation and uses Boyer-Moore pattern matching.

6. Advanced Usage

6.1 Lookaheads and Perl Regex (`-P`)

Extracting values between JSON quotes using PCRE lookbehind and lookahead assertions:

echo '{"status": "healthy", "uptime": 86400}' | grep -P -o '(?<="status": ")[^"]*'

Sample terminal output:

healthy

6.2 Fast Pipeline Checking with Exit Status (`-q`)

Testing if a user exists in /etc/passwd without output:

if grep -q "^deploy:" /etc/passwd; then
    echo "User deploy exists"
fi

Halts reading immediately upon the first match, avoiding processing the remainder of the file.

7. Exit Status, Environment, and Configuration

7.1 Exit Status Codes

Exit Code	Meaning
`0`	Selected lines were found (at least one match).
`1`	No lines were selected (pattern not found).
`>1`	An error occurred (file unreadable, syntax error in pattern).

7.2 Locale Impact on Collation and Range Matching

In UTF-8 locales (en_US.UTF-8), range expressions like [a-z] sort according to dictionary collation order rather than ASCII byte offsets, which can match capital letters. To enforce strict ASCII byte ranges:

LC_ALL=C grep "[a-z]" file

Setting LC_ALL=C also dramatically boosts search performance (often by 500%+) on ASCII text by avoiding multi-byte character validation.

8. Safety, Security, and Portability

8.1 Symlink Loops with `-R` vs `-r`

Warning

Infinite Symlink Recursion Hazard: The uppercase -R (--dereference-recursive) flag instructs grep to follow all symbolic links to directories. If a codebase or log directory contains circular symlinks (e.g. dir/link -> ..), grep -R enters an infinite loop, exhausting memory and file descriptors.

Always prefer lowercase -r (--recursive), which traverses child subdirectories without dereferencing directory symlinks.

8.2 Locale Performance Penalties

Tip

In UTF-8 locales (en_US.UTF-8), range expressions like [a-z] sort according to dictionary collation order rather than ASCII byte offsets. Prefixing large log scans with LC_ALL=C enforces direct byte matching, typically boosting throughput by 300% to 500%:

LC_ALL=C grep "[a-z]" large_archive.log

9. Best Practices

Use -F for Literal String Searches:

[!TIP] Guidance: When searching for static strings containing dots, brackets, or slashes (e.g. URLs or IPs), pass -F. Authoritative Justification: GNU documentation notes that fixed-string search avoids regex compilation overhead and prevents metacharacter interpretation errors.
Prefix Automated Checks with grep -q:

[!TIP] Guidance: Use grep -q in shell conditional statements (if grep -q ...). Authoritative Justification: Terminates input processing upon the first matching line and avoids polluting terminal streams.
Use LC_ALL=C for Massive Log Scans:

[!TIP] Guidance: Prefix large log searches with LC_ALL=C grep .... Authoritative Justification: Bypasses UTF-8 multi-byte decoding, yielding substantial throughput gains.

References

GNU Grep Manual: https://www.gnu.org/software/grep/manual/grep.html
POSIX.1-2024 grep Specification: The Open Group Base Specifications Issue 8. https://pubs.opengroup.org/onlinepubs/9799919799/utilities/grep.html

FilesExpand file tree

linux-grep-tutorial.md

Latest commit

History

linux-grep-tutorial.md

File metadata and controls

1. Introduction

2. Syntax and Command Model

2.1 Canonical Synopsis

2.2 Regular Expression Dialects

3. Options

3.1 Matching and Selection Flags

3.2 Output Control and Formatting

3.3 Context Line Controls

4. Basic Usage

4.1 Quick Reference & Common Invocations

4.2 Case-Insensitive Matching

4.3 Showing Line Numbers

5. Practical Operations

5.1 Extracting IP Addresses with -o and Extended Regex

5.2 Contextual Inspection of Errors

5.3 Recursive Codebase Search Excluding Git Directories

5.4 Fast Fixed-String Search Across Massive Files

6. Advanced Usage

6.1 Lookaheads and Perl Regex (-P)

6.2 Fast Pipeline Checking with Exit Status (-q)

7. Exit Status, Environment, and Configuration

7.1 Exit Status Codes

7.2 Locale Impact on Collation and Range Matching

8. Safety, Security, and Portability

8.1 Symlink Loops with -R vs -r

8.2 Locale Performance Penalties

9. Best Practices

References

5.1 Extracting IP Addresses with `-o` and Extended Regex

6.1 Lookaheads and Perl Regex (`-P`)

6.2 Fast Pipeline Checking with Exit Status (`-q`)

8.1 Symlink Loops with `-R` vs `-r`