CSGREP(1)

💖 CSGREP — ok bestie, let's filter some defects 💖

the csgrep manual, page 1, user commands section, and yes we are doing this together 🎀

---

✨ NAME ✨

csgrep — filter the list of defects by the specified regex-based predicates 🦋

No cap, that's the whole job. You feed it a pile of defects, you tell it what you're looking for with regexes, and it hands back only the ones that match. It's giving bouncer at the club but the club is your error log. 💅

---

🌸 SYNOPSIS 🌸

csgrep [options] [file1.err [...]], where options are:

yes bestie, <cyan>file1.err</cyan> is a placeholder, plug in ur actual files 🫶

---

💜 DESCRIPTION 💜

Okay so here's the thing — every single one of these is a predicate. A defect either matches it or it doesn't. Stack them up and csgrep keeps only the defects that survive the vibe check. ⭐

• --checker arg — a defect matches if its checker matches the given regex. Every defect has exactly one checker assigned, so this one's a one-to-one kinda situation.
• --path arg — a defect matches if the path of its key event matches the given regex. 📁
• --event arg — a defect matches if its key event matches the given regex. Every defect has exactly one key event, and that key event is what decides where the defect lives in the code. That's its whole main-character job. 👑
• --error arg — a defect matches if the message of its key event matches the given regex. 😭
• --hash-v1 arg — a defect matches if its csdiff/v1 fingerprint starts with the given prefix. Prefix matching only, bestie, not a full match.
• --msg arg — a defect matches if any of its messages matches the given regex. Any of them!! It only takes one!!
• --tool arg — a defect matches if it was detected by a tool that matches the given regex. 🔧
• --annot arg — a defect matches if its annotation matches the given regex. 📝
• --src-annot arg — a defect matches if an annotation in the source file matches the given regex. (that's _source_ file, not the error file, iykyk)
• --imp-level arg — a defect matches if the importance level is greater than or equal to the given number. 📈
• --drop-scan-props — do not propagate scan properties. just... let them go 🍃
• -U, --embed-context arg — embed a number of lines of context from the source file for the key event. Snip snip, here's the receipts. ✂️
• --prune-events arg — an event is preserved if its verbosity level is less than or equal to the given number. above that threshold? gone. bye. 💀
• --warning-rate-limit arg — stop processing a warning if the count of its occurrences exceeds the specified limit. okay this one literally taps out once a warning gets too loud.
• --limit-msg-len arg — limit message length by a number provided. short king messages only 👑
• -u, --remove-duplicates — remove defects that are not unique by their key event. dedupe arc, we love to see it ✨
• --set-imp-level arg — set importance level on all defects to the specified value. EVERYONE gets the same level, no favourites.
• --set-scan-prop arg — NAME:VALUE pair to override the specified scan property. 📝
• --strip-path-prefix arg — string prefix to strip from path. Applied after all filters, so don't come for me about ordering.
• --prepend-path-prefix arg — string prefix to prepend to relative paths. Also applied after all filters. 🫶
• --file-glob — expand glob patterns in the names of input files. 🌈
• -i, --ignore-case — ignore case when matching regular expressions. case? never heard of her 💅
• --ignore-parser-warnings — if enabled, parser warnings about the input files do not affect exit code. the warnings still happen, they just don't get to ruin the exit code, periodt.
• --record-input-locations — if enabled, events in json will contain input_line and input_file fields referencing the original location of input file/stream. 📍
• -v, --invert-match — select defects that do not match the selected criteria. flip the whole thing, chaos mode but make it intentional 🦋
• -n, --invert-regex — invert regular expressions in all predicates. not just one. ALL of them. 👀
• -f, --filter-file arg — read custom filtering rules from a file in JSON format. 📄
• --color — use colorized console output. (this is the default if you're connected to a terminal, so like, if you're reading this in a terminal, hi, you already have it)
• --no-color — do not use colorized console output. for when the vibes must be monochrome 🎀
• -q, --quiet — do not report any parsing errors. 🤫
• --mode arg (=grep) — one of: grep, json, evtstat, files, filestat, grouped, sarif, stat, or dig_key_events. default is grep bestie, you're already in it 💖
• --help — print the usage of csgrep. 🫶
• --version — print the version of csgrep. ⭐

---

🎀 OPTIONS 🎀

okay so this section is specifically about the --filter-file option, because that one has ✨lore✨

The --filter-file option takes a list of JSON files in the following format. A missing replace entry is equal to "replace" : "". 📝

{
    "msg-filter" : [
        {
             "checker" : "DIVINE|SYMBIOTIC",
             "regexp" : "memory"
        },
        {
             "checker" : "COMPILER_WARNING",
             "regexp" : "called on unallocated object",
             "replace" : "called correctly, no UB here"
        }
    ]
}

look at her. she's structured. she's specific. she has a msg-filter array and she's not sorry. 💅

---

💀 EXIT STATUS 💀

csgrep exits with status 0 if arguments are valid and input files are parsed successfully. It does not matter whether any defects were matched or not.

yes bestie, read that again. Zero matches is still a zero exit. csgrep is not out here being petty about whether your filter found anything. 🫶

---

🔥 EXAMPLE - CHECKERS, EVENTS, MESSAGES 🔥

Error: FORWARD_NULL (CWE-476):
libhsm.c:1168: assign_zero: Assigning: key_handles = NULL.
libhsm.c:1210: var_deref_op: Dereferencing null pointer key_handles.

In the above example, FORWARD_NULL is the checker, assign_zero and var_deref_op are events, where var_deref_op is the key event and "Dereferencing null pointer key_handles." is the message associated with the key event.

so to recap the cast list: checker = FORWARD_NULL, events = assign_zero and var_deref_op, key event = var_deref_op, message = that whole sentence about the null pointer. she's the one carrying the plot. 👑

---

🌈 DESCRIPTION OF AVAILABLE MODES 🌈

the mode buffet, let's go 🍓

• dig_key_events — for each defect, print only the checker and key event. bare minimum, no extras 💅
• evtstat — print overall checker/key_event statistics for the matched defects. 📊
• files — print only names of error files that contain the matched defects. 📁
• filestat — print statistics of matched defects per individual source files. 📈
• grep — print matched defects using the same format as expected on the input. in goes the format, out comes the format 🦋
• grouped — print matched defects, grouped by error files they originate from. 🧺
• json — print matched defects in a JSON format. 📄
• sarif — print matched defects in a SARIF format. ⭐
• stat — print overall statistics of the matched defects in given error files. 📊

---

and that's the whole page, bestie. every option, every mode, every regex, every caveat, exactly as written, just with ✨personality✨ 🎀

this was csgrep version 3.5.7, from March 2026, and honestly? iconic. ate. no crumbs. 💅🫶💖