doc: express grammar placeholders between angle brackets
This discerns user inputs from verbatim options in the synopsis. Signed-off-by: Jean-Noël Avila <jn.avila@free.fr> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Jean-Noël Avila committed
Nov 6, 2021 at 19:48 UTC
49cbad0edd4dcf53e373e9fd27a9c36a41fb044e
12 files changed
+41
-41
Documentation/git-cherry-pick.txt
+3
-3
@@ -8,7 +8,7 @@ git-cherry-pick - Apply the changes introduced by some existing commits
8
SYNOPSIS
9
--------
10
[verse]
11
-'git cherry-pick' [--edit] [-n] [-m parent-number] [-s] [-x] [--ff]
11
+'git cherry-pick' [--edit] [-n] [-m <parent-number>] [-s] [-x] [--ff]
12
[-S[<keyid>]] <commit>...
13
'git cherry-pick' (--continue | --skip | --abort | --quit)
14
@@ -81,8 +81,8 @@ OPTIONS
81
described above, and `-r` was to disable it. Now the
82
default is not to do `-x` so this option is a no-op.
83
84
--m parent-number::
85
---mainline parent-number::
84
+-m <parent-number>::
85
+--mainline <parent-number>::
86
Usually you cannot cherry-pick a merge because you do not know which
87
side of the merge should be considered the mainline. This
88
option specifies the parent number (starting from 1) of
Documentation/git-config.txt
+23
-23
@@ -9,20 +9,20 @@ git-config - Get and set repository or global options
9
SYNOPSIS
10
--------
11
[verse]
12
-'git config' [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] name [value [value-pattern]]
13
-'git config' [<file-option>] [--type=<type>] --add name value
14
-'git config' [<file-option>] [--type=<type>] [--fixed-value] --replace-all name value [value-pattern]
15
-'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get name [value-pattern]
16
-'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all name [value-pattern]
17
-'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp name_regex [value-pattern]
18
-'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch name URL
19
-'git config' [<file-option>] [--fixed-value] --unset name [value-pattern]
20
-'git config' [<file-option>] [--fixed-value] --unset-all name [value-pattern]
21
-'git config' [<file-option>] --rename-section old_name new_name
22
-'git config' [<file-option>] --remove-section name
12
+'git config' [<file-option>] [--type=<type>] [--fixed-value] [--show-origin] [--show-scope] [-z|--null] <name> [<value> [<value-pattern>]]
13
+'git config' [<file-option>] [--type=<type>] --add <name> <value>
14
+'git config' [<file-option>] [--type=<type>] [--fixed-value] --replace-all <name> <value> [<value-pattern>]
15
+'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get <name> [<value-pattern>]
16
+'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] --get-all <name> [<value-pattern>]
17
+'git config' [<file-option>] [--type=<type>] [--show-origin] [--show-scope] [-z|--null] [--fixed-value] [--name-only] --get-regexp <name-regex> [<value-pattern>]
18
+'git config' [<file-option>] [--type=<type>] [-z|--null] --get-urlmatch <name> <URL>
19
+'git config' [<file-option>] [--fixed-value] --unset <name> [<value-pattern>]
20
+'git config' [<file-option>] [--fixed-value] --unset-all <name> [<value-pattern>]
21
+'git config' [<file-option>] --rename-section <old-name> <new-name>
22
+'git config' [<file-option>] --remove-section <name>
23
'git config' [<file-option>] [--show-origin] [--show-scope] [-z|--null] [--name-only] -l | --list
24
-'git config' [<file-option>] --get-color name [default]
25
-'git config' [<file-option>] --get-colorbool name [stdout-is-tty]
24
+'git config' [<file-option>] --get-color <name> [<default>]
25
+'git config' [<file-option>] --get-colorbool <name> [<stdout-is-tty>]
26
'git config' [<file-option>] -e | --edit
27
28
DESCRIPTION
@@ -102,9 +102,9 @@ OPTIONS
102
in which section and variable names are lowercased, but subsection
103
names are not.
104
105
---get-urlmatch name URL::
105
+--get-urlmatch <name> <URL>::
106
When given a two-part name section.key, the value for
107
- section.<url>.key whose <url> part matches the best to the
107
+ section.<URL>.key whose <URL> part matches the best to the
108
given URL is returned (if no such key exists, the value for
109
section.key is used as a fallback). When given just the
110
section as name, do so for all the keys in the section and
@@ -145,8 +145,8 @@ See also <<FILES>>.
145
read from or written to if `extensions.worktreeConfig` is
146
present. If not it's the same as `--local`.
147
148
--f config-file::
149
---file config-file::
148
+-f <config-file>::
149
+--file <config-file>::
150
For writing options: write to the specified file rather than the
151
repository `.git/config`.
152
+
@@ -155,7 +155,7 @@ available files.
155
+
156
See also <<FILES>>.
157
158
---blob blob::
158
+--blob <blob>::
159
Similar to `--file` but use the given blob instead of a file. E.g.
160
you can use 'master:.gitmodules' to read values from the file
161
'.gitmodules' in the master branch. See "SPECIFYING REVISIONS"
@@ -246,18 +246,18 @@ Valid `<type>`'s include:
246
all queried config options with the scope of that value
247
(local, global, system, command).
248
249
---get-colorbool name [stdout-is-tty]::
249
+--get-colorbool <name> [<stdout-is-tty>]::
250
251
- Find the color setting for `name` (e.g. `color.diff`) and output
252
- "true" or "false". `stdout-is-tty` should be either "true" or
251
+ Find the color setting for `<name>` (e.g. `color.diff`) and output
252
+ "true" or "false". `<stdout-is-tty>` should be either "true" or
253
"false", and is taken into account when configuration says
254
- "auto". If `stdout-is-tty` is missing, then checks the standard
254
+ "auto". If `<stdout-is-tty>` is missing, then checks the standard
255
output of the command itself, and exits with status 0 if color
256
is to be used, or exits with status 1 otherwise.
257
When the color setting for `name` is undefined, the command uses
258
`color.ui` as fallback.
259
260
---get-color name [default]::
260
+--get-color <name> [<default>]::
261
262
Find the color configured for `name` (e.g. `color.diff.new`) and
263
output it as the ANSI color escape sequence to the standard
Documentation/git-cvsexportcommit.txt
+2
-2
@@ -9,8 +9,8 @@ git-cvsexportcommit - Export a single commit to a CVS checkout
9
SYNOPSIS
10
--------
11
[verse]
12
-'git cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d cvsroot]
13
- [-w cvsworkdir] [-W] [-f] [-m msgprefix] [PARENTCOMMIT] COMMITID
12
+'git cvsexportcommit' [-h] [-u] [-v] [-c] [-P] [-p] [-a] [-d <cvsroot>]
13
+ [-w <cvs-workdir>] [-W] [-f] [-m <msgprefix>] [<parent-commit>] <commit-id>
14
15
16
DESCRIPTION
Documentation/git-gui.txt
+1
-1
@@ -8,7 +8,7 @@ git-gui - A portable graphical interface to Git
8
SYNOPSIS
9
--------
10
[verse]
11
-'git gui' [<command>] [arguments]
11
+'git gui' [<command>] [<arguments>]
12
13
DESCRIPTION
14
-----------
Documentation/git-help.txt
+3
-3
@@ -9,12 +9,12 @@ SYNOPSIS
9
--------
10
[verse]
11
'git help' [-a|--all [--[no-]verbose]] [-g|--guides]
12
- [-i|--info|-m|--man|-w|--web] [COMMAND|GUIDE]
12
+ [-i|--info|-m|--man|-w|--web] [<command>|<guide>]
13
14
DESCRIPTION
15
-----------
16
17
-With no options and no COMMAND or GUIDE given, the synopsis of the 'git'
17
+With no options and no '<command>' or '<guide>' given, the synopsis of the 'git'
18
command and a list of the most commonly used Git commands are printed
19
on the standard output.
20
@@ -31,7 +31,7 @@ variables.
31
32
If an alias is given, git shows the definition of the alias on
33
standard output. To get the manual page for the aliased command, use
34
-`git COMMAND --help`.
34
+`git <command> --help`.
35
36
Note that `git --help ...` is identical to `git help ...` because the
37
former is internally converted into the latter.
Documentation/git-http-fetch.txt
+1
-1
@@ -9,7 +9,7 @@ git-http-fetch - Download from a remote Git repository via HTTP
9
SYNOPSIS
10
--------
11
[verse]
12
-'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin | --packfile=<hash> | <commit>] <url>
12
+'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w <filename>] [--recover] [--stdin | --packfile=<hash> | <commit>] <url>
13
14
DESCRIPTION
15
-----------
Documentation/git-init.txt
+1
-1
@@ -12,7 +12,7 @@ SYNOPSIS
12
'git init' [-q | --quiet] [--bare] [--template=<template_directory>]
13
[--separate-git-dir <git dir>] [--object-format=<format>]
14
[-b <branch-name> | --initial-branch=<branch-name>]
15
- [--shared[=<permissions>]] [directory]
15
+ [--shared[=<permissions>]] [<directory>]
16
17
18
DESCRIPTION
Documentation/git-pack-objects.txt
+2
-2
@@ -13,8 +13,8 @@ SYNOPSIS
13
[--no-reuse-delta] [--delta-base-offset] [--non-empty]
14
[--local] [--incremental] [--window=<n>] [--depth=<n>]
15
[--revs [--unpacked | --all]] [--keep-pack=<pack-name>]
16
- [--stdout [--filter=<filter-spec>] | base-name]
17
- [--shallow] [--keep-true-parents] [--[no-]sparse] < object-list
16
+ [--stdout [--filter=<filter-spec>] | <base-name>]
17
+ [--shallow] [--keep-true-parents] [--[no-]sparse] < <object-list>
18
19
20
DESCRIPTION
Documentation/git-pack-redundant.txt
+1
-1
@@ -9,7 +9,7 @@ git-pack-redundant - Find redundant pack files
9
SYNOPSIS
10
--------
11
[verse]
12
-'git pack-redundant' [ --verbose ] [ --alt-odb ] < --all | .pack filename ... >
12
+'git pack-redundant' [ --verbose ] [ --alt-odb ] ( --all | <pack-filename>... )
13
14
DESCRIPTION
15
-----------
Documentation/git-reflog.txt
+2
-2
@@ -17,12 +17,12 @@ The command takes various subcommands, and different options
17
depending on the subcommand:
18
19
[verse]
20
-'git reflog' ['show'] [log-options] [<ref>]
20
+'git reflog' ['show'] [<log-options>] [<ref>]
21
'git reflog expire' [--expire=<time>] [--expire-unreachable=<time>]
22
[--rewrite] [--updateref] [--stale-fix]
23
[--dry-run | -n] [--verbose] [--all [--single-worktree] | <refs>...]
24
'git reflog delete' [--rewrite] [--updateref]
25
- [--dry-run | -n] [--verbose] ref@\{specifier\}...
25
+ [--dry-run | -n] [--verbose] <ref>@\{<specifier>\}...
26
'git reflog exists' <ref>
27
28
Reference logs, or "reflogs", record when the tips of branches and
Documentation/git-sparse-checkout.txt
+1
-1
@@ -11,7 +11,7 @@ given by a list of patterns.
11
SYNOPSIS
12
--------
13
[verse]
14
-'git sparse-checkout <subcommand> [options]'
14
+'git sparse-checkout <subcommand> [<options>]'
15
16
17
DESCRIPTION
Documentation/git-stage.txt
+1
-1
@@ -9,7 +9,7 @@ git-stage - Add file contents to the staging area
9
SYNOPSIS
10
--------
11
[verse]
12
-'git stage' args...
12
+'git stage' <arg>...
13
14
15
DESCRIPTION