From: Jean-Noël Avila Date: Mon, 25 May 2026 10:28:24 +0000 (+0000) Subject: doc: convert git-grep synopsis and options to new style X-Git-Tag: v2.55.0-rc0~18^2~3 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=25d5d60958f1486cb8439863062f66ffef605f18;p=thirdparty%2Fgit.git doc: convert git-grep synopsis and options to new style Convert git-grep.adoc from [verse]/single-quote style to the modern synopsis-block style: - Replace [verse] with [synopsis] in SYNOPSIS block - Change 'git grep' to git grep (no single quotes) - Backtick-quote all OPTIONS terms - Convert inline man page refs: grep(1) -> `grep`(1) - Convert inline command refs: 'git diff' -> `git diff` - Convert prose placeholders: -> __ Signed-off-by: Jean-Noël Avila Signed-off-by: Junio C Hamano --- diff --git a/Documentation/config/grep.adoc b/Documentation/config/grep.adoc index 10041f27b0..83d4b76dd3 100644 --- a/Documentation/config/grep.adoc +++ b/Documentation/config/grep.adoc @@ -1,28 +1,28 @@ -grep.lineNumber:: - If set to true, enable `-n` option by default. +`grep.lineNumber`:: + If set to `true`, enable `-n` option by default. -grep.column:: - If set to true, enable the `--column` option by default. +`grep.column`:: + If set to `true`, enable the `--column` option by default. -grep.patternType:: - Set the default matching behavior. Using a value of 'basic', 'extended', - 'fixed', or 'perl' will enable the `--basic-regexp`, `--extended-regexp`, +`grep.patternType`:: + Set the default matching behavior. Using a value of `basic`, `extended`, + `fixed`, or `perl` will enable the `--basic-regexp`, `--extended-regexp`, `--fixed-strings`, or `--perl-regexp` option accordingly, while the - value 'default' will use the `grep.extendedRegexp` option to choose - between 'basic' and 'extended'. + value `default` will use the `grep.extendedRegexp` option to choose + between `basic` and `extended`. -grep.extendedRegexp:: - If set to true, enable `--extended-regexp` option by default. This +`grep.extendedRegexp`:: + If set to `true`, enable `--extended-regexp` option by default. This option is ignored when the `grep.patternType` option is set to a value - other than 'default'. + other than `default`. -grep.threads:: +`grep.threads`:: 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. -grep.fullName:: - If set to true, enable `--full-name` option by default. +`grep.fullName`:: + If set to `true`, enable `--full-name` option by default. -grep.fallbackToNoIndex:: - If set to true, fall back to `git grep --no-index` if `git grep` - is executed outside of a git repository. Defaults to false. +`grep.fallbackToNoIndex`:: + If set to `true`, fall back to `git grep --no-index` if `git grep` + is executed outside of a git repository. Defaults to `false`. diff --git a/Documentation/git-grep.adoc b/Documentation/git-grep.adoc index a548585d4c..19b3ade16d 100644 --- a/Documentation/git-grep.adoc +++ b/Documentation/git-grep.adoc @@ -8,8 +8,8 @@ git-grep - Print lines matching a pattern SYNOPSIS -------- -[verse] -'git grep' [-a | --text] [-I] [--textconv] [-i | --ignore-case] [-w | --word-regexp] +[synopsis] +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] @@ -41,139 +41,139 @@ characters. An empty string as search expression matches all lines. OPTIONS ------- ---cached:: +`--cached`:: Instead of searching tracked files in the working tree, search blobs registered in the index file. ---untracked:: +`--untracked`:: In addition to searching in the tracked files in the working tree, search also in untracked files. ---no-index:: +`--no-index`:: 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 `grep(1)` utility with its + is rather similar to running the regular `grep`(1) utility with its `-r` option specified, but with some additional benefits, such as - using pathspec patterns to limit paths; see the 'pathspec' entry + using pathspec patterns to limit paths; see the `pathspec` entry in linkgit:gitglossary[7] for more information. + This option cannot be used together with `--cached` or `--untracked`. See also `grep.fallbackToNoIndex` in 'CONFIGURATION' below. ---no-exclude-standard:: +`--no-exclude-standard`:: Also search in ignored files by not honoring the `.gitignore` mechanism. Only useful with `--untracked`. ---exclude-standard:: +`--exclude-standard`:: Do not pay attention to ignored files specified via the `.gitignore` mechanism. Only useful when searching files in the current directory with `--no-index`. ---recurse-submodules:: +`--recurse-submodules`:: Recursively search in each submodule that is active and checked out in the repository. When used in combination with the __ option the prefix of all submodule output will be the name of the parent project's __ object. This option cannot be used together with `--untracked`, and it has no effect if `--no-index` is specified. --a:: ---text:: +`-a`:: +`--text`:: Process binary files as if they were text. ---textconv:: +`--textconv`:: Honor textconv filter settings. ---no-textconv:: +`--no-textconv`:: Do not honor textconv filter settings. This is the default. --i:: ---ignore-case:: +`-i`:: +`--ignore-case`:: Ignore case differences between the patterns and the files. --I:: +`-I`:: Don't match the pattern in binary files. ---max-depth :: - For each given on command line, descend at most +`--max-depth `:: + For each __ given on command line, descend at most __ levels of directories. A value of -1 means no limit. - This option is ignored if contains active wildcards. + This option is ignored if __ contains active wildcards. In other words if "a*" matches a directory named "a*", - "*" is matched literally so --max-depth is still effective. + "*" is matched literally so `--max-depth` is still effective. --r:: ---recursive:: +`-r`:: +`--recursive`:: Same as `--max-depth=-1`; this is the default. ---no-recursive:: +`--no-recursive`:: Same as `--max-depth=0`. --w:: ---word-regexp:: +`-w`:: +`--word-regexp`:: 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). --v:: ---invert-match:: +`-v`:: +`--invert-match`:: Select non-matching lines. --h:: --H:: +`-h`:: +`-H`:: By default, the command shows the filename for each match. `-h` option is used to suppress this output. `-H` is there for completeness and does not do anything except it overrides `-h` given earlier on the command line. ---full-name:: +`--full-name`:: 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. --E:: ---extended-regexp:: --G:: ---basic-regexp:: +`-E`:: +`--extended-regexp`:: +`-G`:: +`--basic-regexp`:: Use POSIX extended/basic regexp for patterns. Default is to use basic regexp. --P:: ---perl-regexp:: +`-P`:: +`--perl-regexp`:: Use Perl-compatible regular expressions for patterns. + Support for these types of regular expressions is an optional compile-time dependency. If Git wasn't compiled with support for them providing this option will cause it to die. --F:: ---fixed-strings:: +`-F`:: +`--fixed-strings`:: Use fixed strings for patterns (don't interpret pattern as a regex). --n:: ---line-number:: +`-n`:: +`--line-number`:: Prefix the line number to matching lines. ---column:: +`--column`:: Prefix the 1-indexed byte-offset of the first match from the start of the matching line. --l:: ---files-with-matches:: ---name-only:: --L:: ---files-without-match:: +`-l`:: +`--files-with-matches`:: +`--name-only`:: +`-L`:: +`--files-without-match`:: Instead of showing every matched line, show only the names of files that contain (or do not contain) matches. - For better compatibility with 'git diff', `--name-only` is a + For better compatibility with `git diff`, `--name-only` is a synonym for `--files-with-matches`. --O[]:: ---open-files-in-pager[=]:: - Open the matching files in the pager (not the output of 'grep'). +`-O[]`:: +`--open-files-in-pager[=]`:: + Open the matching files in the pager (not the output of `grep`). 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 `pager` argument is @@ -181,65 +181,65 @@ providing this option will cause it to die. without a space. If `pager` is unspecified, the default pager will be used (see `core.pager` in linkgit:git-config[1]). --z:: ---null:: +`-z`:: +`--null`:: Use \0 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 `core.quotePath` (see linkgit:git-config[1]). --o:: ---only-matching:: +`-o`:: +`--only-matching`:: Print only the matched (non-empty) parts of a matching line, with each such part on a separate output line. --c:: ---count:: +`-c`:: +`--count`:: Instead of showing every matched line, show the number of lines that match. ---color[=]:: +`--color[=]`:: Show colored matches. - The value must be always (the default), never, or auto. + The value must be `always` (the default), `never`, or `auto`. ---no-color:: +`--no-color`:: Turn off match highlighting, even when the configuration file gives the default to color output. Same as `--color=never`. ---break:: +`--break`:: Print an empty line between matches from different files. ---heading:: +`--heading`:: Show the filename above the matches in that file instead of at the start of each shown line. --p:: ---show-function:: +`-p`:: +`--show-function`:: 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 `git diff` works out patch hunk headers (see 'Defining a custom hunk-header' in linkgit:gitattributes[5]). --:: --C :: ---context :: - Show leading and trailing lines, and place a line +`-`:: +`-C `:: +`--context `:: + Show __ leading and trailing lines, and place a line containing `--` between contiguous groups of matches. --A :: ---after-context :: - Show trailing lines, and place a line containing +`-A `:: +`--after-context `:: + Show __ trailing lines, and place a line containing `--` between contiguous groups of matches. --B :: ---before-context :: - Show leading lines, and place a line containing +`-B `:: +`--before-context `:: + Show __ leading lines, and place a line containing `--` between contiguous groups of matches. --W:: ---function-context:: +`-W`:: +`--function-context`:: 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 @@ -247,22 +247,22 @@ providing this option will cause it to die. `git diff` works out patch hunk headers (see 'Defining a custom hunk-header' in linkgit:gitattributes[5]). --m :: ---max-count :: +`-m `:: +`--max-count `:: Limit the amount of matches per file. When using the `-v` or `--invert-match` 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. ---threads :: - Number of `grep` worker threads to use. See 'NOTES ON THREADS' +`--threads `:: + Number of `grep` worker threads to use. See `NOTES ON THREADS` and `grep.threads` in 'CONFIGURATION' for more information. --f :: - Read patterns from , one per line. +`-f `:: + Read patterns from __, one per line. + -Passing the pattern via allows for providing a search pattern +Passing the pattern via __ allows for providing a search pattern containing a \0. + Not all pattern types support patterns containing \0. Git will error @@ -279,44 +279,44 @@ In future versions we may learn to support patterns containing \0 for more search backends, until then we'll die when the pattern type in question doesn't support them. --e:: +`-e`:: The next parameter is the pattern. This option has to be used for patterns starting with `-` and should be used in scripts passing user input to grep. Multiple patterns are - combined by 'or'. + combined by `or`. ---and:: ---or:: ---not:: -( ... ):: +`--and`:: +`--or`:: +`--not`:: +`( ... )`:: Specify how multiple patterns are combined using Boolean expressions. `--or` is the default operator. `--and` has higher precedence than `--or`. `-e` has to be used for all patterns. ---all-match:: +`--all-match`:: When giving multiple pattern expressions combined with `--or`, this flag is specified to limit the match to files that have lines to match all of them. --q:: ---quiet:: +`-q`:: +`--quiet`:: Do not output matched lines; instead, exit with status 0 when there is a match and with non-zero status when there isn't. -...:: +`...`:: Instead of searching tracked files in the working tree, search blobs in the given trees. -\--:: +`--`:: Signals the end of options; the rest of the parameters - are limiters. + are __ limiters. -...:: +`...`:: If given, limit the search to paths matching at least one pattern. - Both leading paths match and glob(7) patterns are supported. + Both leading paths match and `glob`(7) patterns are supported. + -For more details about the syntax, see the 'pathspec' entry +For more details about the __ syntax, see the `pathspec` entry in linkgit:gitglossary[7]. EXAMPLES