简体中文 ▾ 主题 ▾ 最新版本 ▾ 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）或给定的树对象中的二进制大对象中查找指定的模式。模式是换行符分隔的一个或多个搜索表达式列表。作为搜索表达式的空字符串将匹配所有行。

选项

--cached

不搜索工作树中的已跟踪文件，而是搜索索引文件中注册的二进制大对象。

--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 <深度>

对于命令行上给出的每个 <pathspec>，最多向下深入 <深度> 级目录。值为 -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 开始的字节偏移量。

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

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

-O[<分页器>]
--open-files-in-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[=<何时>]

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

--no-color

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

--break

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

--heading

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

-p
--show-function

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

-<数字>
-C <数字>
--context <数字>

显示 <数字> 行前文和后文，并在连续的匹配组之间放置一行包含 -- 的行。

-A <数字>
--after-context <数字>

显示 <数字> 行后文，并在连续的匹配组之间放置一行包含 -- 的行。

-B <数字>
--before-context <数字>

显示 <数字> 行前文，并在连续的匹配组之间放置一行包含 -- 的行。

-W
--function-context

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

-m <数字>
--max-count <数字>

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

--threads <数字>

要使用的 grep 工作线程数。有关详细信息，请参阅 关于线程的说明 和 CONFIGURATION 中的 grep.threads。

-f <文件>

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

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

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

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

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

-e

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

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

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

--all-match

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

-q
--quiet

不输出匹配的行；相反，在有匹配时以状态 0 退出，在没有匹配时以非零状态退出。

<树>…​

不搜索工作树中的已跟踪文件，而是搜索给定树中的二进制大对象。

--

表示选项结束；其余参数是 <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] 套件的一部分