简体中文 ▾ 主题 ▾ 最新版本 ▾ git-grep 最后更新于 2.45.0

名称

git-grep - 打印匹配模式的行

概要

git grep [-a | --text] [-I] [--textconv] [-i | --ignore-case] [-w | --word-regexp]
	   [-v | --invert-match] [-h|-H] [--full-name]
	   [-E | --extended-regexp] [-G | --basic-regexp]
	   [-P | --perl-regexp]
	   [-F | --fixed-strings] [-n | --line-number] [--column]
	   [-l | --files-with-matches] [-L | --files-without-match]
	   [(-O | --open-files-in-pager) [<pager>]]
	   [-z | --null]
	   [ -o | --only-matching ] [-c | --count] [--all-match] [-q | --quiet]
	   [--max-depth <depth>] [--[no-]recursive]
	   [--color[=<when>] | --no-color]
	   [--break] [--heading] [-p | --show-function]
	   [-A <post-context>] [-B <pre-context>] [-C <context>]
	   [-W | --function-context]
	   [(-m | --max-count) <num>]
	   [--threads <num>]
	   [-f <file>] [-e] <pattern>
	   [--and|--or|--not|(|)|-e <pattern>…​]
	   [--recurse-submodules] [--parent-basename <basename>]
	   [ [--[no-]exclude-standard] [--cached | --untracked | --no-index] | <tree>…​]
	   [--] [<pathspec>…​]

描述

在工作树中已跟踪的文件、索引文件中注册的 blob 或给定树对象中的 blob 中查找指定的模式。模式是由换行符分隔的一个或多个搜索表达式的列表。空字符串作为搜索表达式会匹配所有行。

选项

--cached

不搜索工作树中已跟踪的文件，而是搜索索引文件中注册的 blob。

--untracked

除了在工作树中已跟踪的文件中搜索外，还搜索未跟踪的文件。

--no-index

在当前目录中搜索不由 Git 管理的文件，或忽略当前目录由 Git 管理。这与运行常规的 grep(1) 工具并指定其 -r 选项非常相似，但有一些额外的好处，例如使用 pathspec 模式来限制路径；有关更多信息，请参阅 gitglossary[7] 中的 pathspec 条目。

此选项不能与 --cached 或 --untracked 一起使用。另请参阅下面的 CONFIGURATION 中的 grep.fallbackToNoIndex。

--no-exclude-standard

通过不遵循 .gitignore 机制，也在被忽略的文件中搜索。仅在与 --untracked 一起使用时有用。

--exclude-standard

不关注通过 .gitignore 机制指定的被忽略文件。仅在与 --no-index 一起搜索当前目录中的文件时有用。

--recurse-submodules

在仓库中每个活跃且已检出的子模块中递归搜索。当与 <tree> 选项结合使用时，所有子模块输出的前缀将是父项目 <tree> 对象的名称。此选项不能与 --untracked 一起使用，如果指定了 --no-index 则无效。

-a
--text

将二进制文件视为文本文件进行处理。

--textconv

遵循 textconv 过滤器设置。

--no-textconv

不遵循 textconv 过滤器设置。这是默认值。

-i
--ignore-case

忽略模式和文件之间的字母大小写差异。

-I

不在二进制文件中匹配模式。

--max-depth <depth>

对于命令行上给出的每个 <pathspec>，最多下潜 <depth> 层目录。值为 -1 表示没有限制。如果 <pathspec> 包含活动的通配符，则此选项将被忽略。换句话说，如果 "a*" 匹配名为 "a*" 的目录，则 "*" 被字面匹配，因此 --max-depth 仍然有效。

-r
--recursive

与 --max-depth=-1 相同；这是默认值。

--no-recursive

与 --max-depth=0 相同。

-w
--word-regexp

仅在单词边界匹配模式（要么从行首开始，要么前面是非单词字符；要么在行尾结束，要么后面是非单词字符）。

-v
--invert-match

选择不匹配的行。

-h
-H

默认情况下，此命令显示每个匹配的文件名。-h 选项用于抑制此输出。-H 用于完整性，除了覆盖命令行上早先给出的 -h 之外，不执行任何操作。

--full-name

当从子目录运行时，此命令通常输出相对于当前目录的路径。此选项强制路径输出为相对于项目顶级目录。

-E
--extended-regexp
-G
--basic-regexp

对模式使用 POSIX 扩展/基本正则表达式。默认使用基本正则表达式。

-P
--perl-regexp

对模式使用 Perl 兼容的正则表达式。

对这些类型的正则表达式的支持是一个可选的编译时依赖项。如果 Git 在编译时没有支持这些功能，则提供此选项将导致其停止运行。

-F
--fixed-strings

对模式使用固定字符串（不将模式解释为正则表达式）。

-n
--line-number

在匹配行的前面添加行号。

--column

在匹配行的开头，为第一个匹配项添加 1-indexed 字节偏移量作为前缀。

-l
--files-with-matches
--name-only
-L
--files-without-match

不显示每个匹配行，而是仅显示包含（或不包含）匹配的文件名。为了更好地与 git diff 兼容，--name-only 是 --files-with-matches 的同义词。

-O[<pager>]
--open-files-in-pager[=<pager>]

在分页器中打开匹配的文件（而不是 grep 的输出）。如果分页器恰好是“less”或“vi”，并且用户只指定了一个模式，则第一个文件会自动定位到第一个匹配项。pager 参数是可选的；如果指定，它必须紧跟选项，中间没有空格。如果未指定 pager，将使用默认分页器（参见 git-config[1] 中的 core.pager）。

-z
--null

在输出中使用 \0 作为路径名的分隔符，并按原样打印它们。如果没有此选项，带有“不寻常”字符的路径名将按照配置变量 core.quotePath 的说明进行引用（参见 git-config[1]）。

-o
--only-matching

只打印匹配行中匹配的（非空）部分，每个这样的部分单独占一行输出。

-c
--count

不显示每个匹配行，而是显示匹配的行数。

--color[=<when>]

显示彩色匹配。值必须是 always（默认）、never 或 auto。

--no-color

关闭匹配高亮显示，即使配置文件默认输出彩色。与 --color=never 相同。

--break

在来自不同文件的匹配之间打印一个空行。

--heading

在该文件中匹配项上方显示文件名，而不是在每行显示行的开头显示。

-p
--show-function

显示包含匹配函数名称的前一行，除非匹配行本身就是函数名称。名称的确定方式与 git diff 确定补丁块头的方式相同（参见 gitattributes[5] 中 Defining a custom hunk-header）。

-<num>
-C <num>
--context <num>

显示 <num> 行前导和尾随行，并在连续的匹配组之间放置包含 -- 的行。

-A <num>
--after-context <num>

显示 <num> 行尾随行，并在连续的匹配组之间放置包含 -- 的行。

-B <num>
--before-context <num>

显示 <num> 行前导行，并在连续的匹配组之间放置包含 -- 的行。

-W
--function-context

显示从包含函数名称的前一行到下一个函数名称之前一行的周围文本，有效地显示找到匹配项的整个函数。函数名称的确定方式与 git diff 确定补丁块头的方式相同（参见 gitattributes[5] 中 Defining a custom hunk-header）。

-m <num>
--max-count <num>

限制每个文件的匹配数量。当使用 -v 或 --invert-match 选项时，搜索将在指定数量的非匹配项之后停止。值为 -1 将返回无限结果（默认）。值为 0 将立即以非零状态退出。

--threads <num>

要使用的 grep 工作线程数。有关更多信息，请参阅 NOTES ON THREADS 和 CONFIGURATION 中的 grep.threads。

-f <file>

从 <file> 读取模式，每行一个。

通过 <file> 传递模式允许提供包含 \0 的搜索模式。

并非所有模式类型都支持包含 \0 的模式。如果给定的模式类型不支持此类模式，Git 将报错。针对 PCRE v2 后端编译时，--perl-regexp 模式类型对此类模式的支持最广泛。

在 Git 2.23.0 之前的版本中，包含 \0 的模式会被默默地视为固定字符串。这从未被记录，例如，包含 \0 的非 ASCII 模式与 --ignore-case 之间也存在奇怪且未记录的交互。

在未来的版本中，我们可能会学会为更多搜索后端支持包含 \0 的模式，在此之前，如果相关模式类型不支持它们，我们将停止运行。

-e

下一个参数是模式。此选项必须用于以 - 开头的模式，并且应在将用户输入传递给 grep 的脚本中使用。多个模式通过 or 组合。

--and
--or
--not
( …​ )

指定如何使用布尔表达式组合多个模式。--or 是默认运算符。--and 的优先级高于 --or。-e 必须用于所有模式。

--all-match

当给出多个与 --or 组合的模式表达式时，此标志用于将匹配限制为包含所有匹配行的文件。

-q
--quiet

不输出匹配行；而是当存在匹配时以状态 0 退出，当不存在时以非零状态退出。

<tree>…​

不搜索工作树中已跟踪的文件，而是搜索给定树中的 blob。

--

表示选项的结束；其余参数是 <pathspec> 限制符。

<pathspec>…​

如果给定，将搜索限制为至少匹配一个模式的路径。支持前导路径匹配和 glob(7) 模式。

有关 <pathspec> 语法的更多详细信息，请参阅 gitglossary[7] 中的 pathspec 条目。

示例

git grep time_t' -- *.[ch]

在工作目录及其子目录中所有已跟踪的 .c 和 .h 文件中查找 time_t。

git grep -e '#define' --and \( -e MAX_PATH -e PATH_MAX \)

查找包含 #define 以及 MAX_PATH 或 PATH_MAX 的行。

git grep --all-match -e NODE -e Unexpected

在包含同时匹配两者的行的文件中，查找包含 NODE 或 Unexpected 的行。

git grep solution -- :^Documentation

查找 solution，排除 Documentation 中的文件。

关于线程的注意事项

当使用 --open-files-in-pager 时，--threads 选项（以及 grep.threads 配置）将被忽略，强制执行单线程。

当在对象存储中进行 grep（使用 --cached 或给定树对象）时，如果给定 --textconv 且文本转换过多，则多线程运行可能会比单线程慢。因此，如果在这种情况下遇到性能低下，可能需要使用 --threads=1。

配置

本节中以下所有内容均从 git-config[1] 文档中选择性地包含。内容与彼处相同：

grep.lineNumber

如果设置为 true，默认启用 -n 选项。

grep.column

如果设置为 true，默认启用 --column 选项。

grep.patternType

设置默认匹配行为。使用 basic、extended、fixed 或 perl 的值将分别启用 --basic-regexp、--extended-regexp、--fixed-strings 或 --perl-regexp 选项，而值 default 将使用 grep.extendedRegexp 选项在 basic 和 extended 之间进行选择。

grep.extendedRegexp

如果设置为 true，默认启用 --extended-regexp 选项。当 grep.patternType 选项设置为除 default 以外的值时，此选项将被忽略。

grep.threads

要使用的 grep 工作线程数。如果未设置（或设置为 0），Git 将使用与可用逻辑核心数相同的线程数。

grep.fullName

如果设置为 true，默认启用 --full-name 选项。

grep.fallbackToNoIndex

如果设置为 true，当在 Git 仓库外部执行 git grep 时，回退到 git grep --no-index。默认为 false。

GIT

Git[1] 套件的一部分

scroll-to-top