git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH v4 1/6] t/README: document test_grep helper

From
Michael Montalbo via GitGitGadget <gitgitgadget@gmail.com>
Date
Jul 6, 2026, 05:01 UTC
Message-ID
<44d5db91bc3e951a6d2e34acc545b7093783bdaf.1783314119.git.gitgitgadget@gmail.com>
In-Reply-To
<pull.2135.v4.git.1783314119.gitgitgadget@gmail.com>
From: Michael Montalbo <mmontalbo@gmail.com>

test_grep is a wrapper around grep for test assertions that prints the file contents on failure for easier debugging. It also accepts '!' as its first argument for negation, which preserves the diagnostic output that '! test_grep' would suppress.

Despite being widely used (and the preferred replacement for bare grep in assertions), test_grep has no entry in t/README alongside the other documented helpers like test_cmp and test_line_count. Add one.

Signed-off-by: Michael Montalbo <mmontalbo@gmail.com>
---
 t/README | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)
diff --git a/t/README b/t/README
index 085921be4b..4252774f86 100644
--- a/t/README
+++ b/t/README
@@ -1039,6 +1039,40 @@ see test-lib-functions.sh for the full list and their options.
 
    Check whether a file has the length it is expected to.
 
+ - test_grep [!] [<grep-options>] <pattern> <file>
+
+   Check whether <file> contains a line matching <pattern>, or
+   with '!' that no line matches.  Use this instead of bare
+   'grep <pattern> <file>' in test assertions.  On failure,
+   test_grep prints the contents of <file> for easier debugging,
+   whereas a bare 'grep' would fail silently.
+
+   For negation, pass '!' as the first argument:
+
+	test_grep ! "^diff --git" actual
+
+   Do not negate by writing '! test_grep', as that suppresses the
+   diagnostic output.
+
+   test_grep should only be used as a test assertion.  When grep
+   is used as a data filter (e.g. 'grep -v "^index" actual >filtered')
+   or inside a command substitution (e.g. '$(grep -c ...)'), plain
+   'grep' is the right choice because the exit code is not the
+   assertion itself.
+
+   test_grep requires <file> to exist and will BUG otherwise, so
+   use it only where the file is guaranteed to exist at that point.
+   When a file's presence is conditional (a backend-specific file,
+   or a path that only exists on some platforms, such as an NTFS
+   8.3 short name), guard the assertion on that condition (a
+   prerequisite, or a 'test -e' on the path) and use test_grep
+   inside the guard:
+
+	if test_have_prereq REFFILES
+	then
+		test_grep ! "$refname" .git/packed-refs
+	fi
+
  - test_path_is_file <path>
    test_path_is_dir <path>
    test_path_is_missing <path>
-- 
gitgitgadget
Previous: Michael Montalbo via GitGitGadgetNext: Michael Montalbo via GitGitGadget
Message 35 of 40 in “t: add lint-style.pl and convert grep to test_grep”
  1. 0/6 t: add lint-style.pl and convert grep to test_grepMichael Montalbo via GitGitGadget, Jun 4, 2026
  2. 1/6 t/README: document test_grep helperMichael Montalbo via GitGitGadget, Jun 4, 2026
  3. 3/6 t: fix Lexer line count for $() inside double-quoted stringsMichael Montalbo via GitGitGadget, Jun 4, 2026
  4. 2/6 t: extract chainlint's parser into shared moduleMichael Montalbo via GitGitGadget, Jun 4, 2026
  5. 4/6 t: add lint-style.pl with test_grep negation ruleMichael Montalbo via GitGitGadget, Jun 4, 2026
  6. D. Ben KnobleJun 4, 2026
  7. Michael MontalboJun 4, 2026
  8. 5/6 t: fix grep assertions missing file argumentsMichael Montalbo via GitGitGadget, Jun 4, 2026
  9. 6/6 t: lint and convert grep assertions to test_grepMichael Montalbo via GitGitGadget, Jun 4, 2026
  10. Junio C HamanoJun 8, 2026
  11. Michael MontalboJun 13, 2026
  12. 0/6 t: add greplint.pl and convert grep to test_grepMichael Montalbo via GitGitGadget, Jun 13, 2026
  13. 1/6 t/README: document test_grep helperMichael Montalbo via GitGitGadget, Jun 13, 2026
  14. 2/6 t: fix grep assertions missing file argumentsMichael Montalbo via GitGitGadget, Jun 13, 2026
  15. 3/6 t: extract chainlint's parser into shared moduleMichael Montalbo via GitGitGadget, Jun 13, 2026
  16. 4/6 t: fix Lexer line count for $() inside double-quoted stringsMichael Montalbo via GitGitGadget, Jun 13, 2026
  17. 5/6 t: convert grep assertions to test_grepMichael Montalbo via GitGitGadget, Jun 13, 2026
  18. SZEDER GáborJun 27, 2026
  19. Junio C HamanoJun 27, 2026
  20. Junio C HamanoJun 28, 2026
  21. Junio C HamanoJun 28, 2026
  22. Junio C HamanoJun 29, 2026
  23. Michael MontalboJul 2, 2026
  24. 6/6 t: add greplint to detect bare grep assertionsMichael Montalbo via GitGitGadget, Jun 13, 2026
  25. 0/6 t: add greplint.pl and convert grep to test_grepMichael Montalbo via GitGitGadget, Jul 3, 2026
  26. 1/6 t/README: document test_grep helperMichael Montalbo via GitGitGadget, Jul 3, 2026
  27. 2/6 t: fix grep assertions missing file argumentsMichael Montalbo via GitGitGadget, Jul 3, 2026
  28. 3/6 t: extract chainlint's parser into shared moduleMichael Montalbo via GitGitGadget, Jul 3, 2026
  29. 4/6 t: fix Lexer line count for $() inside double-quoted stringsMichael Montalbo via GitGitGadget, Jul 3, 2026
  30. 6/6 t: add greplint to detect bare grep assertionsMichael Montalbo via GitGitGadget, Jul 3, 2026
  31. 5/6 t: convert grep assertions to test_grepMichael Montalbo via GitGitGadget, Jul 3, 2026
  32. Junio C HamanoJul 5, 2026
  33. Michael MontalboJul 5, 2026
  34. 0/6 t: add greplint.pl and convert grep to test_grepMichael Montalbo via GitGitGadget, Jul 6, 2026
  35. 1/6 t/README: document test_grep helperMichael Montalbo via GitGitGadget, Jul 6, 2026
  36. 2/6 t: fix grep assertions missing file argumentsMichael Montalbo via GitGitGadget, Jul 6, 2026
  37. 3/6 t: extract chainlint's parser into shared moduleMichael Montalbo via GitGitGadget, Jul 6, 2026
  38. 4/6 t: fix Lexer line count for $() inside double-quoted stringsMichael Montalbo via GitGitGadget, Jul 6, 2026
  39. 6/6 t: add greplint to detect bare grep assertionsMichael Montalbo via GitGitGadget, Jul 6, 2026
  40. 5/6 t: convert grep assertions to test_grepMichael Montalbo via GitGitGadget, Jul 6, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.