logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

git-grep.1 (15514B)


  1. '\" t
  2. .\" Title: git-grep
  3. .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
  4. .\" Generator: DocBook XSL Stylesheets v1.79.2 <http://docbook.sf.net/>
  5. .\" Date: 2025-03-14
  6. .\" Manual: Git Manual
  7. .\" Source: Git 2.49.0
  8. .\" Language: English
  9. .\"
  10. .TH "GIT\-GREP" "1" "2025-03-14" "Git 2\&.49\&.0" "Git Manual"
  11. .\" -----------------------------------------------------------------
  12. .\" * Define some portability stuff
  13. .\" -----------------------------------------------------------------
  14. .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15. .\" http://bugs.debian.org/507673
  16. .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17. .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18. .ie \n(.g .ds Aq \(aq
  19. .el .ds Aq '
  20. .\" -----------------------------------------------------------------
  21. .\" * set default formatting
  22. .\" -----------------------------------------------------------------
  23. .\" disable hyphenation
  24. .nh
  25. .\" disable justification (adjust text to left margin only)
  26. .ad l
  27. .\" -----------------------------------------------------------------
  28. .\" * MAIN CONTENT STARTS HERE *
  29. .\" -----------------------------------------------------------------
  30. .SH "NAME"
  31. git-grep \- Print lines matching a pattern
  32. .SH "SYNOPSIS"
  33. .sp
  34. .nf
  35. \fIgit grep\fR [\-a | \-\-text] [\-I] [\-\-textconv] [\-i | \-\-ignore\-case] [\-w | \-\-word\-regexp]
  36. [\-v | \-\-invert\-match] [\-h|\-H] [\-\-full\-name]
  37. [\-E | \-\-extended\-regexp] [\-G | \-\-basic\-regexp]
  38. [\-P | \-\-perl\-regexp]
  39. [\-F | \-\-fixed\-strings] [\-n | \-\-line\-number] [\-\-column]
  40. [\-l | \-\-files\-with\-matches] [\-L | \-\-files\-without\-match]
  41. [(\-O | \-\-open\-files\-in\-pager) [<pager>]]
  42. [\-z | \-\-null]
  43. [ \-o | \-\-only\-matching ] [\-c | \-\-count] [\-\-all\-match] [\-q | \-\-quiet]
  44. [\-\-max\-depth <depth>] [\-\-[no\-]recursive]
  45. [\-\-color[=<when>] | \-\-no\-color]
  46. [\-\-break] [\-\-heading] [\-p | \-\-show\-function]
  47. [\-A <post\-context>] [\-B <pre\-context>] [\-C <context>]
  48. [\-W | \-\-function\-context]
  49. [(\-m | \-\-max\-count) <num>]
  50. [\-\-threads <num>]
  51. [\-f <file>] [\-e] <pattern>
  52. [\-\-and|\-\-or|\-\-not|(|)|\-e <pattern>\&...\:]
  53. [\-\-recurse\-submodules] [\-\-parent\-basename <basename>]
  54. [ [\-\-[no\-]exclude\-standard] [\-\-cached | \-\-untracked | \-\-no\-index] | <tree>\&...\:]
  55. [\-\-] [<pathspec>\&...\:]
  56. .fi
  57. .SH "DESCRIPTION"
  58. .sp
  59. Look for specified patterns in the tracked files in the work tree, blobs registered in the index file, or blobs in given tree objects\&. Patterns are lists of one or more search expressions separated by newline characters\&. An empty string as search expression matches all lines\&.
  60. .SH "OPTIONS"
  61. .PP
  62. \-\-cached
  63. .RS 4
  64. Instead of searching tracked files in the working tree, search blobs registered in the index file\&.
  65. .RE
  66. .PP
  67. \-\-untracked
  68. .RS 4
  69. In addition to searching in the tracked files in the working tree, search also in untracked files\&.
  70. .RE
  71. .PP
  72. \-\-no\-index
  73. .RS 4
  74. Search files in the current directory that is not managed by Git, or by ignoring that the current directory is managed by Git\&. This is rather similar to running the regular
  75. \fBgrep\fR(\fB1\fR) utility with its
  76. \fB\-r\fR
  77. option specified, but with some additional benefits, such as using pathspec patterns to limit paths; see the
  78. \fIpathspec\fR
  79. entry in
  80. \fBgitglossary\fR(7)
  81. for more information\&.
  82. .sp
  83. This option cannot be used together with
  84. \fB\-\-cached\fR
  85. or
  86. \fB\-\-untracked\fR\&. See also
  87. \fBgrep\&.fallbackToNoIndex\fR
  88. in
  89. \fICONFIGURATION\fR
  90. below\&.
  91. .RE
  92. .PP
  93. \-\-no\-exclude\-standard
  94. .RS 4
  95. Also search in ignored files by not honoring the \&.\fBgitignore\fR
  96. mechanism\&. Only useful with
  97. \fB\-\-untracked\fR\&.
  98. .RE
  99. .PP
  100. \-\-exclude\-standard
  101. .RS 4
  102. Do not pay attention to ignored files specified via the \&.\fBgitignore\fR
  103. mechanism\&. Only useful when searching files in the current directory with
  104. \fB\-\-no\-index\fR\&.
  105. .RE
  106. .PP
  107. \-\-recurse\-submodules
  108. .RS 4
  109. Recursively search in each submodule that is active and checked out in the repository\&. When used in combination with the
  110. \fI<tree>\fR
  111. option the prefix of all submodule output will be the name of the parent project\(cqs
  112. \fI<tree>\fR
  113. object\&. This option cannot be used together with
  114. \fB\-\-untracked\fR, and it has no effect if
  115. \fB\-\-no\-index\fR
  116. is specified\&.
  117. .RE
  118. .PP
  119. \-a, \-\-text
  120. .RS 4
  121. Process binary files as if they were text\&.
  122. .RE
  123. .PP
  124. \-\-textconv
  125. .RS 4
  126. Honor textconv filter settings\&.
  127. .RE
  128. .PP
  129. \-\-no\-textconv
  130. .RS 4
  131. Do not honor textconv filter settings\&. This is the default\&.
  132. .RE
  133. .PP
  134. \-i, \-\-ignore\-case
  135. .RS 4
  136. Ignore case differences between the patterns and the files\&.
  137. .RE
  138. .PP
  139. \-I
  140. .RS 4
  141. Don\(cqt match the pattern in binary files\&.
  142. .RE
  143. .PP
  144. \-\-max\-depth <depth>
  145. .RS 4
  146. For each <pathspec> given on command line, descend at most <depth> levels of directories\&. A value of \-1 means no limit\&. This option is ignored if <pathspec> contains active wildcards\&. In other words if "a*" matches a directory named "a*", "*" is matched literally so \-\-max\-depth is still effective\&.
  147. .RE
  148. .PP
  149. \-r, \-\-recursive
  150. .RS 4
  151. Same as
  152. \fB\-\-max\-depth=\-1\fR; this is the default\&.
  153. .RE
  154. .PP
  155. \-\-no\-recursive
  156. .RS 4
  157. Same as
  158. \fB\-\-max\-depth=0\fR\&.
  159. .RE
  160. .PP
  161. \-w, \-\-word\-regexp
  162. .RS 4
  163. Match the pattern only at word boundary (either begin at the beginning of a line, or preceded by a non\-word character; end at the end of a line or followed by a non\-word character)\&.
  164. .RE
  165. .PP
  166. \-v, \-\-invert\-match
  167. .RS 4
  168. Select non\-matching lines\&.
  169. .RE
  170. .PP
  171. \-h, \-H
  172. .RS 4
  173. By default, the command shows the filename for each match\&.
  174. \fB\-h\fR
  175. option is used to suppress this output\&.
  176. \fB\-H\fR
  177. is there for completeness and does not do anything except it overrides
  178. \fB\-h\fR
  179. given earlier on the command line\&.
  180. .RE
  181. .PP
  182. \-\-full\-name
  183. .RS 4
  184. When run from a subdirectory, the command usually outputs paths relative to the current directory\&. This option forces paths to be output relative to the project top directory\&.
  185. .RE
  186. .PP
  187. \-E, \-\-extended\-regexp, \-G, \-\-basic\-regexp
  188. .RS 4
  189. Use POSIX extended/basic regexp for patterns\&. Default is to use basic regexp\&.
  190. .RE
  191. .PP
  192. \-P, \-\-perl\-regexp
  193. .RS 4
  194. Use Perl\-compatible regular expressions for patterns\&.
  195. .sp
  196. Support for these types of regular expressions is an optional compile\-time dependency\&. If Git wasn\(cqt compiled with support for them providing this option will cause it to die\&.
  197. .RE
  198. .PP
  199. \-F, \-\-fixed\-strings
  200. .RS 4
  201. Use fixed strings for patterns (don\(cqt interpret pattern as a regex)\&.
  202. .RE
  203. .PP
  204. \-n, \-\-line\-number
  205. .RS 4
  206. Prefix the line number to matching lines\&.
  207. .RE
  208. .PP
  209. \-\-column
  210. .RS 4
  211. Prefix the 1\-indexed byte\-offset of the first match from the start of the matching line\&.
  212. .RE
  213. .PP
  214. \-l, \-\-files\-with\-matches, \-\-name\-only, \-L, \-\-files\-without\-match
  215. .RS 4
  216. Instead of showing every matched line, show only the names of files that contain (or do not contain) matches\&. For better compatibility with
  217. \fIgit diff\fR,
  218. \fB\-\-name\-only\fR
  219. is a synonym for
  220. \fB\-\-files\-with\-matches\fR\&.
  221. .RE
  222. .PP
  223. \-O[<pager>], \-\-open\-files\-in\-pager[=<pager>]
  224. .RS 4
  225. Open the matching files in the pager (not the output of
  226. \fIgrep\fR)\&. If the pager happens to be "less" or "vi", and the user specified only one pattern, the first file is positioned at the first match automatically\&. The
  227. \fBpager\fR
  228. argument is optional; if specified, it must be stuck to the option without a space\&. If
  229. \fBpager\fR
  230. is unspecified, the default pager will be used (see
  231. \fBcore\&.pager\fR
  232. in
  233. \fBgit-config\fR(1))\&.
  234. .RE
  235. .PP
  236. \-z, \-\-null
  237. .RS 4
  238. Use \e0 as the delimiter for pathnames in the output, and print them verbatim\&. Without this option, pathnames with "unusual" characters are quoted as explained for the configuration variable
  239. \fBcore\&.quotePath\fR
  240. (see
  241. \fBgit-config\fR(1))\&.
  242. .RE
  243. .PP
  244. \-o, \-\-only\-matching
  245. .RS 4
  246. Print only the matched (non\-empty) parts of a matching line, with each such part on a separate output line\&.
  247. .RE
  248. .PP
  249. \-c, \-\-count
  250. .RS 4
  251. Instead of showing every matched line, show the number of lines that match\&.
  252. .RE
  253. .PP
  254. \-\-color[=<when>]
  255. .RS 4
  256. Show colored matches\&. The value must be always (the default), never, or auto\&.
  257. .RE
  258. .PP
  259. \-\-no\-color
  260. .RS 4
  261. Turn off match highlighting, even when the configuration file gives the default to color output\&. Same as
  262. \fB\-\-color=never\fR\&.
  263. .RE
  264. .PP
  265. \-\-break
  266. .RS 4
  267. Print an empty line between matches from different files\&.
  268. .RE
  269. .PP
  270. \-\-heading
  271. .RS 4
  272. Show the filename above the matches in that file instead of at the start of each shown line\&.
  273. .RE
  274. .PP
  275. \-p, \-\-show\-function
  276. .RS 4
  277. Show the preceding line that contains the function name of the match, unless the matching line is a function name itself\&. The name is determined in the same way as
  278. \fBgit\fR
  279. \fBdiff\fR
  280. works out patch hunk headers (see
  281. \fIDefining a custom hunk\-header\fR
  282. in
  283. \fBgitattributes\fR(5))\&.
  284. .RE
  285. .PP
  286. \-<num>, \-C <num>, \-\-context <num>
  287. .RS 4
  288. Show <num> leading and trailing lines, and place a line containing
  289. \fB\-\-\fR
  290. between contiguous groups of matches\&.
  291. .RE
  292. .PP
  293. \-A <num>, \-\-after\-context <num>
  294. .RS 4
  295. Show <num> trailing lines, and place a line containing
  296. \fB\-\-\fR
  297. between contiguous groups of matches\&.
  298. .RE
  299. .PP
  300. \-B <num>, \-\-before\-context <num>
  301. .RS 4
  302. Show <num> leading lines, and place a line containing
  303. \fB\-\-\fR
  304. between contiguous groups of matches\&.
  305. .RE
  306. .PP
  307. \-W, \-\-function\-context
  308. .RS 4
  309. Show the surrounding text from the previous line containing a function name up to the one before the next function name, effectively showing the whole function in which the match was found\&. The function names are determined in the same way as
  310. \fBgit\fR
  311. \fBdiff\fR
  312. works out patch hunk headers (see
  313. \fIDefining a custom hunk\-header\fR
  314. in
  315. \fBgitattributes\fR(5))\&.
  316. .RE
  317. .PP
  318. \-m <num>, \-\-max\-count <num>
  319. .RS 4
  320. Limit the amount of matches per file\&. When using the
  321. \fB\-v\fR
  322. or
  323. \fB\-\-invert\-match\fR
  324. option, the search stops after the specified number of non\-matches\&. A value of \-1 will return unlimited results (the default)\&. A value of 0 will exit immediately with a non\-zero status\&.
  325. .RE
  326. .PP
  327. \-\-threads <num>
  328. .RS 4
  329. Number of
  330. \fBgrep\fR
  331. worker threads to use\&. See
  332. \fINOTES ON THREADS\fR
  333. and
  334. \fBgrep\&.threads\fR
  335. in
  336. \fICONFIGURATION\fR
  337. for more information\&.
  338. .RE
  339. .PP
  340. \-f <file>
  341. .RS 4
  342. Read patterns from <file>, one per line\&.
  343. .sp
  344. Passing the pattern via <file> allows for providing a search pattern containing a \e0\&.
  345. .sp
  346. Not all pattern types support patterns containing \e0\&. Git will error out if a given pattern type can\(cqt support such a pattern\&. The
  347. \fB\-\-perl\-regexp\fR
  348. pattern type when compiled against the PCRE v2 backend has the widest support for these types of patterns\&.
  349. .sp
  350. In versions of Git before 2\&.23\&.0 patterns containing \e0 would be silently considered fixed\&. This was never documented, there were also odd and undocumented interactions between e\&.g\&. non\-ASCII patterns containing \e0 and
  351. \fB\-\-ignore\-case\fR\&.
  352. .sp
  353. In future versions we may learn to support patterns containing \e0 for more search backends, until then we\(cqll die when the pattern type in question doesn\(cqt support them\&.
  354. .RE
  355. .PP
  356. \-e
  357. .RS 4
  358. The next parameter is the pattern\&. This option has to be used for patterns starting with
  359. \fB\-\fR
  360. and should be used in scripts passing user input to grep\&. Multiple patterns are combined by
  361. \fIor\fR\&.
  362. .RE
  363. .PP
  364. \-\-and, \-\-or, \-\-not, ( \&...\: )
  365. .RS 4
  366. Specify how multiple patterns are combined using Boolean expressions\&.
  367. \fB\-\-or\fR
  368. is the default operator\&.
  369. \fB\-\-and\fR
  370. has higher precedence than
  371. \fB\-\-or\fR\&.
  372. \fB\-e\fR
  373. has to be used for all patterns\&.
  374. .RE
  375. .PP
  376. \-\-all\-match
  377. .RS 4
  378. When giving multiple pattern expressions combined with
  379. \fB\-\-or\fR, this flag is specified to limit the match to files that have lines to match all of them\&.
  380. .RE
  381. .PP
  382. \-q, \-\-quiet
  383. .RS 4
  384. Do not output matched lines; instead, exit with status 0 when there is a match and with non\-zero status when there isn\(cqt\&.
  385. .RE
  386. .PP
  387. <tree>\&...\:
  388. .RS 4
  389. Instead of searching tracked files in the working tree, search blobs in the given trees\&.
  390. .RE
  391. .PP
  392. \-\-
  393. .RS 4
  394. Signals the end of options; the rest of the parameters are <pathspec> limiters\&.
  395. .RE
  396. .PP
  397. <pathspec>\&...\:
  398. .RS 4
  399. If given, limit the search to paths matching at least one pattern\&. Both leading paths match and glob(7) patterns are supported\&.
  400. .sp
  401. For more details about the <pathspec> syntax, see the
  402. \fIpathspec\fR
  403. entry in
  404. \fBgitglossary\fR(7)\&.
  405. .RE
  406. .SH "EXAMPLES"
  407. .PP
  408. \fBgit\fR \fBgrep\fR \*(Aqtime_t\*(Aq \fB\-\-\fR \*(Aq*\&.[\fBch\fR]\*(Aq
  409. .RS 4
  410. Looks for
  411. \fBtime_t\fR
  412. in all tracked \&.c and \&.h files in the working directory and its subdirectories\&.
  413. .RE
  414. .PP
  415. \fBgit\fR \fBgrep\fR \fB\-e\fR \*(Aq#define\*(Aq \fB\-\-and\fR \e( \fB\-e\fR \fBMAX_PATH\fR \fB\-e\fR \fBPATH_MAX\fR \e)
  416. .RS 4
  417. Looks for a line that has #define and either
  418. \fBMAX_PATH\fR
  419. or
  420. \fBPATH_MAX\fR\&.
  421. .RE
  422. .PP
  423. \fBgit\fR \fBgrep\fR \fB\-\-all\-match\fR \fB\-e\fR \fBNODE\fR \fB\-e\fR \fBUnexpected\fR
  424. .RS 4
  425. Looks for a line that has
  426. \fBNODE\fR
  427. or
  428. \fBUnexpected\fR
  429. in files that have lines that match both\&.
  430. .RE
  431. .PP
  432. \fBgit\fR \fBgrep\fR \fBsolution\fR \fB\-\-\fR \fB:^Documentation\fR
  433. .RS 4
  434. Looks for
  435. \fBsolution\fR, excluding files in
  436. \fBDocumentation\fR\&.
  437. .RE
  438. .SH "NOTES ON THREADS"
  439. .sp
  440. The \fB\-\-threads\fR option (and the \fBgrep\&.threads\fR configuration) will be ignored when \fB\-\-open\-files\-in\-pager\fR is used, forcing a single\-threaded execution\&.
  441. .sp
  442. When grepping the object store (with \fB\-\-cached\fR or giving tree objects), running with multiple threads might perform slower than single\-threaded if \fB\-\-textconv\fR is given and there are too many text conversions\&. Thus, if low performance is experienced in this case, it might be desirable to use \fB\-\-threads=1\fR\&.
  443. .SH "CONFIGURATION"
  444. .sp
  445. Everything below this line in this section is selectively included from the \fBgit-config\fR(1) documentation\&. The content is the same as what\(cqs found there:
  446. .PP
  447. grep\&.lineNumber
  448. .RS 4
  449. If set to true, enable
  450. \fB\-n\fR
  451. option by default\&.
  452. .RE
  453. .PP
  454. grep\&.column
  455. .RS 4
  456. If set to true, enable the
  457. \fB\-\-column\fR
  458. option by default\&.
  459. .RE
  460. .PP
  461. grep\&.patternType
  462. .RS 4
  463. Set the default matching behavior\&. Using a value of
  464. \fIbasic\fR,
  465. \fIextended\fR,
  466. \fIfixed\fR, or
  467. \fIperl\fR
  468. will enable the
  469. \fB\-\-basic\-regexp\fR,
  470. \fB\-\-extended\-regexp\fR,
  471. \fB\-\-fixed\-strings\fR, or
  472. \fB\-\-perl\-regexp\fR
  473. option accordingly, while the value
  474. \fIdefault\fR
  475. will use the
  476. \fBgrep\&.extendedRegexp\fR
  477. option to choose between
  478. \fIbasic\fR
  479. and
  480. \fIextended\fR\&.
  481. .RE
  482. .PP
  483. grep\&.extendedRegexp
  484. .RS 4
  485. If set to true, enable
  486. \fB\-\-extended\-regexp\fR
  487. option by default\&. This option is ignored when the
  488. \fBgrep\&.patternType\fR
  489. option is set to a value other than
  490. \fIdefault\fR\&.
  491. .RE
  492. .PP
  493. grep\&.threads
  494. .RS 4
  495. Number of grep worker threads to use\&. If unset (or set to 0), Git will use as many threads as the number of logical cores available\&.
  496. .RE
  497. .PP
  498. grep\&.fullName
  499. .RS 4
  500. If set to true, enable
  501. \fB\-\-full\-name\fR
  502. option by default\&.
  503. .RE
  504. .PP
  505. grep\&.fallbackToNoIndex
  506. .RS 4
  507. If set to true, fall back to
  508. \fBgit\fR
  509. \fBgrep\fR
  510. \fB\-\-no\-index\fR
  511. if
  512. \fBgit\fR
  513. \fBgrep\fR
  514. is executed outside of a git repository\&. Defaults to false\&.
  515. .RE
  516. .SH "GIT"
  517. .sp
  518. Part of the \fBgit\fR(1) suite