diff-merges: improve --diff-merges documentation
* Put descriptions of convenience shortcuts first, so they are the first things reader observes rather than lengthy detailed stuff. * Get rid of very long line containing all the --diff-merges formats by replacing them with <format>, and putting each supported format on its own line. Signed-off-by: Sergey Organov <sorganov@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Sergey Organov committed
Oct 9, 2023 at 19:05 UTC
be3820c60cc82e0ded1d3f3dcc19fbd59ce56aa2
2 files changed
+55
-47
Documentation/diff-options.txt
+54
-46
@@ -37,66 +37,74 @@ endif::git-diff[]
37
endif::git-format-patch[]
38
39
ifdef::git-log[]
40
---diff-merges=(off|none|on|first-parent|1|separate|m|combined|c|dense-combined|cc|remerge|r)::
40
+-m::
41
+ Show diffs for merge commits in the default format. This is
42
+ similar to '--diff-merges=on', except `-m` will
43
+ produce no output unless `-p` is given as well.
44
+
45
+-c::
46
+ Produce combined diff output for merge commits.
47
+ Shortcut for '--diff-merges=combined -p'.
48
+
49
+--cc::
50
+ Produce dense combined diff output for merge commits.
51
+ Shortcut for '--diff-merges=dense-combined -p'.
52
+
53
+--remerge-diff::
54
+ Produce remerge-diff output for merge commits.
55
+ Shortcut for '--diff-merges=remerge -p'.
56
+
57
--no-diff-merges::
58
+ Synonym for '--diff-merges=off'.
59
+
60
+--diff-merges=<format>::
61
Specify diff format to be used for merge commits. Default is
43
- {diff-merges-default} unless `--first-parent` is in use, in which case
44
- `first-parent` is the default.
62
+ {diff-merges-default} unless `--first-parent` is in use, in
63
+ which case `first-parent` is the default.
64
++
65
+The following formats are supported:
66
+
46
---diff-merges=(off|none):::
47
---no-diff-merges:::
67
+--
68
+off, none::
69
Disable output of diffs for merge commits. Useful to override
70
implied value.
71
+
51
---diff-merges=on:::
52
---diff-merges=m:::
53
--m:::
54
- This option makes diff output for merge commits to be shown in
55
- the default format. `-m` will produce the output only if `-p`
56
- is given as well. The default format could be changed using
57
- `log.diffMerges` configuration parameter, which default value
72
+on, m::
73
+ Make diff output for merge commits to be shown in the default
74
+ format. The default format could be changed using
75
+ `log.diffMerges` configuration variable, whose default value
76
is `separate`.
77
+
60
---diff-merges=first-parent:::
61
---diff-merges=1:::
62
- This option makes merge commits show the full diff with
63
- respect to the first parent only.
78
+first-parent, 1::
79
+ Show full diff with respect to first parent. This is the same
80
+ format as `--patch` produces for non-merge commits.
81
++
82
+separate::
83
+ Show full diff with respect to each of parents.
84
+ Separate log entry and diff is generated for each parent.
85
++
86
+combined, c::
87
+ Show differences from each of the parents to the merge
88
+ result simultaneously instead of showing pairwise diff between
89
+ a parent and the result one at a time. Furthermore, it lists
90
+ only files which were modified from all parents.
91
+
65
---diff-merges=separate:::
66
- This makes merge commits show the full diff with respect to
67
- each of the parents. Separate log entry and diff is generated
68
- for each parent.
92
+dense-combined, cc::
93
+ Further compress output produced by `--diff-merges=combined`
94
+ by omitting uninteresting hunks whose contents in the parents
95
+ have only two variants and the merge result picks one of them
96
+ without modification.
97
+
70
---diff-merges=remerge:::
71
---diff-merges=r:::
72
---remerge-diff:::
73
- With this option, two-parent merge commits are remerged to
74
- create a temporary tree object -- potentially containing files
75
- with conflict markers and such. A diff is then shown between
76
- that temporary tree and the actual merge commit.
98
+remerge, r::
99
+ Remerge two-parent merge commits to create a temporary tree
100
+ object--potentially containing files with conflict markers
101
+ and such. A diff is then shown between that temporary tree
102
+ and the actual merge commit.
103
+
104
The output emitted when this option is used is subject to change, and
105
so is its interaction with other options (unless explicitly
106
documented).
81
-+
82
---diff-merges=combined:::
83
---diff-merges=c:::
84
--c:::
85
- With this option, diff output for a merge commit shows the
86
- differences from each of the parents to the merge result
87
- simultaneously instead of showing pairwise diff between a
88
- parent and the result one at a time. Furthermore, it lists
89
- only files which were modified from all parents. `-c` implies
90
- `-p`.
91
-+
92
---diff-merges=dense-combined:::
93
---diff-merges=cc:::
94
---cc:::
95
- With this option the output produced by
96
- `--diff-merges=combined` is further compressed by omitting
97
- uninteresting hunks whose contents in the parents have only
98
- two variants and the merge result picks one of them without
99
- modification. `--cc` implies `-p`.
107
+--
108
109
--combined-all-paths::
110
This flag causes combined diffs (used for merge commits) to
Documentation/git-log.txt
+1
-1
@@ -124,7 +124,7 @@ Note that unless one of `--diff-merges` variants (including short
124
will not show a diff, even if a diff format like `--patch` is
125
selected, nor will they match search options like `-S`. The exception
126
is when `--first-parent` is in use, in which case `first-parent` is
127
-the default format.
127
+the default format for merge commits.
128
129
:git-log: 1
130
:diff-merges-default: `off`