CSVGREP(1)

✨ NAME ✨

csvgrep — okay so this is the csvgrep Documentation, and it lives inside the csvkit crew, and bestie, it is literally grep but for tables. 🌸

---

💖 DESCRIPTION 💖

So the whole vibe of csvgrep is: you have tabular data, and you only want the rows where certain columns contain a value you're looking for, or match a regular expression. That's it. That's the whole job. Filter tabular data to only those rows where certain columns contain a given value or match a regular expression. Slay. 💅

Here's the usage, verbatim, no cap:

usage: csvgrep [-h] [-d DELIMITER] [-t] [-q QUOTECHAR] [-u {0,1,2,3}] [-b]
               [-p ESCAPECHAR] [-z FIELD_SIZE_LIMIT] [-e ENCODING] [-S] [-H]
               [-K SKIP_LINES] [-v] [-l] [--zero] [-V] [-n] [-c COLUMNS]
               [-m PATTERN] [-r REGEX] [-f MATCHFILE] [-i] [-a]
               [FILE]

Search CSV files. Like the Unix "grep" command, but for tabular data.

positional arguments:
  FILE                  The CSV file to operate on. If omitted, will accept
                        input as piped data via STDIN.

optional arguments:
  -h, --help            show this help message and exit
  -n, --names           Display column names and indices from the input CSV
                        and exit.
  -c COLUMNS, --columns COLUMNS
                        A comma-separated list of column indices, names or
                        ranges to be searched, e.g. "1,id,3-5".
  -m PATTERN, --match PATTERN
                        A string to search for.
  -r REGEX, --regex REGEX
                        A regular expression to match.
  -f MATCHFILE, --file MATCHFILE
                        A path to a file. For each row, if any line in the
                        file (stripped of line separators) is an exact match
                        of the cell value, the row matches.
  -i, --invert-match    Select non-matching rows, instead of matching rows.
  -a, --any-match       Select rows in which any column matches, instead of
                        all columns.

🎀 the rundown, one flag at a time 🎀

• -h, --help — shows this help message and then dips. the classic. ✨
• -n, --names — displays the column names and indices from the input CSV and then exits. perfect for when you're like "wait which column is which" 🙈
• -c COLUMNS, --columns COLUMNS — a comma-separated list of column indices, names or ranges you wanna search, like "1,id,3-5". this is your "where am I even looking" flag. 👑
• -m PATTERN, --match PATTERN — a string to search for. exact vibes.
• -r REGEX, --regex REGEX — a regular expression to match. for the girlies who speak in regex 💅
• -f MATCHFILE, --file MATCHFILE — a path to a file. for each row: if any line in that file (stripped of line separators) is an exact match of the cell value, then the row matches. yes, the whole file. it's giving lookup table energy. 🦋
• -i, --invert-match — selects non-matching rows instead of matching rows. the "not me" flag, fr fr.
• -a, --any-match — selects rows where any column matches, instead of all columns. any instead of all, got it? 🫶

See also: Arguments common to all tools.

⚠️ NOTE: Even though -m, -r, and -f are listed as "optional" arguments, you must specify one of them. like... they said optional but they did not mean optional bestie 😭 pick one.

---

🌈 EXAMPLES 🌈

Search for the row relating to Illinois:

csvgrep -c 1 -m ILLINOIS examples/realdata/FY09_EDU_Recipients_by_State.csv

Search for rows relating to states with names beginning with the letter "I":

csvgrep -c 1 -r "^I" examples/realdata/FY09_EDU_Recipients_by_State.csv

Search for rows that do not contain an empty state cell:

csvgrep -c 1 -r "^$" -i examples/realdata/FY09_EDU_Recipients_by_State.csv

Perform a case-insensitive search:

csvgrep -c 1 -r "(?i)illinois" examples/realdata/FY09_EDU_Recipients_by_State.csv

Remove comment rows:

printf "a,b\n1,2\n# a comment\n3,4" | csvgrep --invert-match -c1 -r '^#'

Get the indices of the columns that contain matching text (\x1e is the Record Separator (RS) character):

csvgrep -m 22 -a -c 1- examples/realdata/FY09_EDU_Recipients_by_State.csv | csvformat -M $'\x1e' | xargs -d $'\x1e' -n1 sh -c 'echo $0 | csvcut -n' | grep 22

⚠️ NOTE: This last example is not performant. 💀 it works! but it is not performant. choose wisely.

---

💜 AUTHOR 💜

Christopher Groskopf and contributors

---

⭐ COPYRIGHT ⭐

2016, Christopher Groskopf and James McKinney

---

and that's the whole page bestie 🫶 go filter some rows, you're gonna ate — this was csvkit version 2.2.0, dated Aug 16, 2024, page CSVGREP(1). ily, bye! 💖✨🎀