@matheusbsbs / matheus-bagliano / commits / 5594be68ea

doc: convert git-range-diff manual page to synopsis style

* convert commands and options to synopsis style * use _<placeholder>_ for arguments * small style fixes 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 Apr 4, 2026 at 17:12 UTC 5594be68eaa0fc9c87f7a50be09b85762415f070
1 file changed +25 -25
Documentation/git-range-diff.adoc
+25 -25
@@ -7,8 +7,8 @@ git-range-diff - Compare two commit ranges (e.g. two versions of a branch)
7
8 SYNOPSIS
9 --------
10 -[verse]
11 -'git range-diff' [--color=[<when>]] [--no-color] [<diff-options>]
10 +[synopsis]
11 +git range-diff [--color=[<when>]] [--no-color] [<diff-options>]
12 [--no-dual-color] [--creation-factor=<factor>]
13 [--left-only | --right-only] [--diff-merges=<format>]
14 [--remerge-diff]
@@ -21,14 +21,14 @@ DESCRIPTION
21 This command shows the differences between two versions of a patch
22 series, or more generally, two commit ranges (ignoring merge commits).
23
24 -In the presence of `<path>` arguments, these commit ranges are limited
24 +In the presence of _<path>_ arguments, these commit ranges are limited
25 accordingly.
26
27 To that end, it first finds pairs of commits from both commit ranges
28 that correspond with each other. Two commits are said to correspond when
29 the diff between their patches (i.e. the author information, the commit
30 message and the commit diff) is reasonably small compared to the
31 -patches' size. See ``Algorithm`` below for details.
31 +patches' size. See 'Algorithm' below for details.
32
33 Finally, the list of matching commits is shown in the order of the
34 second commit range, with unmatched commits being inserted just after
@@ -37,7 +37,7 @@ all of their ancestors have been shown.
37 There are three ways to specify the commit ranges:
38
39 - `<range1> <range2>`: Either commit range can be of the form
40 - `<base>..<rev>`, `<rev>^!` or `<rev>^-<n>`. See `SPECIFYING RANGES`
40 + `<base>..<rev>`, `<rev>^!` or `<rev>^-<n>`. See 'SPECIFYING RANGES'
41 in linkgit:gitrevisions[7] for more details.
42
43 - `<rev1>...<rev2>`. This is equivalent to
@@ -48,7 +48,7 @@ There are three ways to specify the commit ranges:
48
49 OPTIONS
50 -------
51 ---no-dual-color::
51 +`--no-dual-color`::
52 When the commit diffs differ, `git range-diff` recreates the
53 original diffs' coloring, and adds outer -/+ diff markers with
54 the *background* being red/green to make it easier to see e.g.
@@ -56,33 +56,33 @@ OPTIONS
56 +
57 Additionally, the commit diff lines that are only present in the first commit
58 range are shown "dimmed" (this can be overridden using the `color.diff.<slot>`
59 -config setting where `<slot>` is one of `contextDimmed`, `oldDimmed` and
59 +config setting where _<slot>_ is one of `contextDimmed`, `oldDimmed` and
60 `newDimmed`), and the commit diff lines that are only present in the second
61 commit range are shown in bold (which can be overridden using the config
62 -settings `color.diff.<slot>` with `<slot>` being one of `contextBold`,
62 +settings `color.diff.<slot>` with _<slot>_ being one of `contextBold`,
63 `oldBold` or `newBold`).
64 +
65 This is known to `range-diff` as "dual coloring". Use `--no-dual-color`
66 to revert to color all lines according to the outer diff markers
67 (and completely ignore the inner diff when it comes to color).
68
69 ---creation-factor=<percent>::
70 - Set the creation/deletion cost fudge factor to `<percent>`.
69 +`--creation-factor=<percent>`::
70 + Set the creation/deletion cost fudge factor to _<percent>_.
71 Defaults to 60. Try a larger value if `git range-diff` erroneously
72 considers a large change a total rewrite (deletion of one commit
73 and addition of another), and a smaller one in the reverse case.
74 - See the ``Algorithm`` section below for an explanation of why this is
74 + See the 'Algorithm' section below for an explanation of why this is
75 needed.
76
77 ---left-only::
77 +`--left-only`::
78 Suppress commits that are missing from the first specified range
79 - (or the "left range" when using the `<rev1>...<rev2>` format).
79 + (or the "left range" when using the `<rev1>...<rev2>` form).
80
81 ---right-only::
81 +`--right-only`::
82 Suppress commits that are missing from the second specified range
83 - (or the "right range" when using the `<rev1>...<rev2>` format).
83 + (or the "right range" when using the `<rev1>...<rev2>` form).
84
85 ---diff-merges=<format>::
85 +`--diff-merges=<format>`::
86 Instead of ignoring merge commits, generate diffs for them using the
87 corresponding `--diff-merges=<format>` option of linkgit:git-log[1],
88 and include them in the comparison.
@@ -93,30 +93,30 @@ have produced. In other words, if a merge commit is the result of a
93 non-conflicting `git merge`, the `remerge` mode will represent it with an empty
94 diff.
95
96 ---remerge-diff::
96 +`--remerge-diff`::
97 Convenience option, equivalent to `--diff-merges=remerge`.
98
99 ---notes[=<ref>]::
100 ---no-notes::
99 +`--notes[=<ref>]`::
100 +`--no-notes`::
101 This flag is passed to the `git log` program
102 (see linkgit:git-log[1]) that generates the patches.
103
104 -<range1> <range2>::
104 +`<range1> <range2>`::
105 Compare the commits specified by the two ranges, where
106 - `<range1>` is considered an older version of `<range2>`.
106 + _<range1>_ is considered an older version of _<range2>_.
107
108 -<rev1>...<rev2>::
108 +`<rev1>...<rev2>`::
109 Equivalent to passing `<rev2>..<rev1>` and `<rev1>..<rev2>`.
110
111 -<base> <rev1> <rev2>::
111 +`<base> <rev1> <rev2>`::
112 Equivalent to passing `<base>..<rev1>` and `<base>..<rev2>`.
113 - Note that `<base>` does not need to be the exact branch point
113 + Note that _<base>_ does not need to be the exact branch point
114 of the branches. Example: after rebasing a branch `my-topic`,
115 `git range-diff my-topic@{u} my-topic@{1} my-topic` would
116 show the differences introduced by the rebase.
117
118 `git range-diff` also accepts the regular diff options (see
119 -linkgit:git-diff[1]), most notably the `--color=[<when>]` and
119 +linkgit:git-diff[1]), most notably the `--color[=<when>]` and
120 `--no-color` options. These options are used when generating the "diff
121 between patches", i.e. to compare the author, commit message and diff of
122 corresponding old/new commits. There is currently no means to tweak most of the