简体中文 ▾ 主题 ▾ 最新版本 ▾ 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 管理。这非常类似于使用 regular grep(1) 实用程序及其 -r 选项，但具有一些额外的优点，例如使用路径说明符模式来限制路径；有关更多信息，请参阅 gitglossary[7] 中的pathspec 条目。

此选项不能与 --cached 或 --untracked 一起使用。另请参阅下面的配置中的 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 索引字节偏移处加上前缀。

-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] 中的定义自定义块标题）。

-<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] 中的定义自定义块标题）。

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

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

--threads <num>

使用的 grep 工作线程数。请参阅关于线程的说明和配置中的 grep.threads 以获取更多信息。

-f <file>

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

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

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

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

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

-e

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

--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 配置），强制执行单线程。

当对对象存储进行 grepping 时（使用 --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 grep 在 git 仓库外执行时，会回退到 git grep --no-index。默认为 false。

GIT

Git[1] 套件的一部分