From: Michael Montalbo via GitGitGadget Date: Fri, 03 Jul 2026 04:54:20 GMT Subject: [PATCH v3 1/6] t/README: document test_grep helper Message-ID: In-Reply-To: From: Michael Montalbo 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 --- t/README | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/t/README b/t/README index 085921be4b..928331fc7d 100644 --- a/t/README +++ b/t/README @@ -1039,6 +1039,32 @@ 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 [!] [] + + Check whether contains a line matching , or + with '!' that no line matches. Use this instead of bare + 'grep ' in test assertions. On failure, + test_grep prints the contents of 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 to exist and will BUG otherwise. + 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), keep a plain guarded 'grep' instead. + - test_path_is_file test_path_is_dir test_path_is_missing -- gitgitgadget