t/README: document test_grep helper
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> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Michael Montalbo committed
Jul 6, 2026 at 05:01 UTC
afd278b35a9aff3ca75fcc393dac53f0a0c1eae6
1 file changed
+34
t/README
+34
@@ -1039,6 +1039,40 @@ see test-lib-functions.sh for the full list and their options.
1039
1040
Check whether a file has the length it is expected to.
1041
1042
+ - test_grep [!] [<grep-options>] <pattern> <file>
1043
+
1044
+ Check whether <file> contains a line matching <pattern>, or
1045
+ with '!' that no line matches. Use this instead of bare
1046
+ 'grep <pattern> <file>' in test assertions. On failure,
1047
+ test_grep prints the contents of <file> for easier debugging,
1048
+ whereas a bare 'grep' would fail silently.
1049
+
1050
+ For negation, pass '!' as the first argument:
1051
+
1052
+ test_grep ! "^diff --git" actual
1053
+
1054
+ Do not negate by writing '! test_grep', as that suppresses the
1055
+ diagnostic output.
1056
+
1057
+ test_grep should only be used as a test assertion. When grep
1058
+ is used as a data filter (e.g. 'grep -v "^index" actual >filtered')
1059
+ or inside a command substitution (e.g. '$(grep -c ...)'), plain
1060
+ 'grep' is the right choice because the exit code is not the
1061
+ assertion itself.
1062
+
1063
+ test_grep requires <file> to exist and will BUG otherwise, so
1064
+ use it only where the file is guaranteed to exist at that point.
1065
+ When a file's presence is conditional (a backend-specific file,
1066
+ or a path that only exists on some platforms, such as an NTFS
1067
+ 8.3 short name), guard the assertion on that condition (a
1068
+ prerequisite, or a 'test -e' on the path) and use test_grep
1069
+ inside the guard:
1070
+
1071
+ if test_have_prereq REFFILES
1072
+ then
1073
+ test_grep ! "$refname" .git/packed-refs
1074
+ fi
1075
+
1076
- test_path_is_file <path>
1077
test_path_is_dir <path>
1078
test_path_is_missing <path>