Autogenerated HTML docs for v2.30.0-452-gfb7fa

32 files changed, 480 insertions, 144 deletions

diff --git a/RelNotes/2.30.1.txt b/RelNotes/2.30.1.txt
new file mode 100644
index 000000000..3760bd17f
--- /dev/null
+++ b/RelNotes/2.30.1.txt
@@ -0,0 +1,47 @@
+Git v2.30.1 Release Notes
+=========================
+
+This release is primarily to merge fixes accumulated on the 'master'
+front to prepare for 2.31 release that are still relevant to 2.30.x
+maintenance track.
+
+Fixes since v2.30
+-----------------
+
+ * "git fetch --recurse-submodules" failed to update a submodule
+   when it has an uninitialized (hence of no interest to the user)
+   sub-submodule, which has been corrected.
+
+ * Command line error of "git rebase" are diagnosed earlier.
+
+ * "git stash" did not work well in a sparsely checked out working
+   tree.
+
+ * Some tests expect that "ls -l" output has either '-' or 'x' for
+   group executable bit, but setgid bit can be inherited from parent
+   directory and make these fields 'S' or 's' instead, causing test
+   failures.
+
+ * "git for-each-repo --config=<var> <cmd>" should not run <cmd> for
+   any repository when the configuration variable <var> is not defined
+   even once.
+
+ * "git mergetool --tool-help" was broken in 2.29 and failed to list
+   all the available tools.
+
+ * Fix for procedure to building CI test environment for mac.
+
+ * Newline characters in the host and path part of git:// URL are
+   now forbidden.
+
+ * When more than one commit with the same patch ID appears on one
+   side, "git log --cherry-pick A...B" did not exclude them all when a
+   commit with the same patch ID appears on the other side.  Now it
+   does.
+
+ * Documentation for "git fsck" lost stale bits that has become
+   incorrect.
+
+ * Doc for packfile URI feature has been clarified.
+
+Also contains minor documentation updates and code clean-ups.
diff --git a/RelNotes/2.31.0.txt b/RelNotes/2.31.0.txt
index 2a722e1e0..905c9aa52 100644
--- a/RelNotes/2.31.0.txt
+++ b/RelNotes/2.31.0.txt
@@ -48,6 +48,13 @@ UI, Workflows & Features
    standard input.  Also, it now does not lose refs whey they point
    at the same object.
 
+ * "git log" learned a new "--diff-merges=<how>" option.
+
+ * "git ls-files" can and does show multiple entries when the index is
+   unmerged, which is a source for confusion unless -s/-u option is in
+   use.  A new option --deduplicate has been introduced.
+
+
 Performance, Internal Implementation, Development Support etc.
 
  * A 3-year old test that was not testing anything useful has been
@@ -80,6 +87,38 @@ Performance, Internal Implementation, Development Support etc.
  * The .use_shell flag in struct child_process that is passed to
    run_command() API has been clarified with a bit more documentation.
 
+ * Document, clean-up and optimize the code around the cache-tree
+   extension in the index.
+
+ * The ls-refs protocol operation has been optimized to narrow the
+   sub-hierarchy of refs/ it walks to produce response.
+
+ * When removing many branches and tags, the code used to do so one
+   ref at a time.  There is another API it can use to delete multiple
+   refs, and it makes quite a lot of performance difference when the
+   refs are packed.
+
+ * The "pack-objects" command needs to iterate over all the tags when
+   automatic tag following is enabled, but it actually iterated over
+   all refs and then discarded everything outside "refs/tags/"
+   hierarchy, which was quite wasteful.
+
+ * A perf script was made more portable.
+   (merge f08b6c553d jk/p5303-sed-portability-fix later to maint).
+
+ * Our setting of GitHub CI test jobs were a bit too eager to give up
+   once there is even one failure found.  Tweak the knob to allow
+   other jobs keep running even when we see a failure, so that we can
+   find more failures in a single run.
+   (merge 2b0e14f640 pb/ci-matrix-wo-shortcut later to maint).
+
+ * We've carried compatibility codepaths for compilers without
+   variadic macros for quite some time, but the world may be ready for
+   them to be removed.  Force compilation failure on exotic platforms
+   where variadic macros are not available to find out who screams in
+   such a way that we can easily revert if it turns out that the world
+   is not yet ready.
+
 
 Fixes since v2.30
 -----------------
@@ -159,3 +198,4 @@ Fixes since v2.30
    (merge a4a1ca22ef tb/local-clone-race-doc later to maint).
    (merge 6a8c89d053 ma/more-opaque-lock-file later to maint).
    (merge 4a5ec7d166 js/skip-dashed-built-ins-from-config-mak later to maint).
+   (merge 6eaf624dea pb/blame-funcname-range-userdiff later to maint).
diff --git a/diff-generate-patch.txt b/diff-generate-patch.txt
index b10ff4caa..2db8eacc3 100644
--- a/diff-generate-patch.txt
+++ b/diff-generate-patch.txt
@@ -81,9 +81,9 @@ Combined diff format
 Any diff-generating command can take the `-c` or `--cc` option to
 produce a 'combined diff' when showing a merge. This is the default
 format when showing merges with linkgit:git-diff[1] or
-linkgit:git-show[1]. Note also that you can give the `-m` option to any
-of these commands to force generation of diffs with individual parents
-of a merge.
+linkgit:git-show[1]. Note also that you can give suitable
+`--diff-merges` option to any of these commands to force generation of
+diffs in specific format.
 
 A "combined diff" format looks like this:
 
diff --git a/diff-options.txt b/diff-options.txt
index 746b144c7..e5733ccb2 100644
--- a/diff-options.txt
+++ b/diff-options.txt
@@ -33,6 +33,57 @@ endif::git-diff[]
 	show the patch by default, or to cancel the effect of `--patch`.
 endif::git-format-patch[]
 
+ifdef::git-log[]
+--diff-merges=(off|none|first-parent|1|separate|m|combined|c|dense-combined|cc)::
+--no-diff-merges::
+	Specify diff format to be used for merge commits. Default is
+	{diff-merges-default} unless `--first-parent` is in use, in which case
+	`first-parent` is the default.
++
+--diff-merges=(off|none):::
+--no-diff-merges:::
+	Disable output of diffs for merge commits. Useful to override
+	implied value.
++
+--diff-merges=first-parent:::
+--diff-merges=1:::
+	This option makes merge commits show the full diff with
+	respect to the first parent only.
++
+--diff-merges=separate:::
+--diff-merges=m:::
+-m:::
+	This makes merge commits show the full diff with respect to
+	each of the parents. Separate log entry and diff is generated
+	for each parent. `-m` doesn't produce any output without `-p`.
++
+--diff-merges=combined:::
+--diff-merges=c:::
+-c:::
+	With this option, diff output for a merge commit shows the
+	differences from each of the parents to the merge result
+	simultaneously instead of showing pairwise diff between a
+	parent and the result one at a time. Furthermore, it lists
+	only files which were modified from all parents. `-c` implies
+	`-p`.
++
+--diff-merges=dense-combined:::
+--diff-merges=cc:::
+--cc:::
+	With this option the output produced by
+	`--diff-merges=combined` is further compressed by omitting
+	uninteresting hunks whose contents in the parents have only
+	two variants and the merge result picks one of them without
+	modification.  `--cc` implies `-p`.
+
+--combined-all-paths::
+	This flag causes combined diffs (used for merge commits) to
+	list the name of the file from all parents.  It thus only has
+	effect when `--diff-merges=[dense-]combined` is in use, and
+	is likely only useful if filename changes are detected (i.e.
+	when either rename or copy detection have been requested).
+endif::git-log[]
+
 -U<n>::
 --unified=<n>::
 	Generate diffs with <n> lines of context instead of
diff --git a/git-diff-files.html b/git-diff-files.html
index 51c8c99b4..49b10af0a 100644
--- a/git-diff-files.html
+++ b/git-diff-files.html
@@ -2411,9 +2411,9 @@ rename to a</code></pre>
 <div class="paragraph"><p>Any diff-generating command can take the <code>-c</code> or <code>--cc</code> option to

 produce a <em>combined diff</em> when showing a merge. This is the default

 format when showing merges with <a href="git-diff.html">git-diff(1)</a> or

-<a href="git-show.html">git-show(1)</a>. Note also that you can give the <code>-m</code> option to any

-of these commands to force generation of diffs with individual parents

-of a merge.</p></div>

+<a href="git-show.html">git-show(1)</a>. Note also that you can give suitable

+<code>--diff-merges</code> option to any of these commands to force generation of

+diffs in specific format.</p></div>

 <div class="paragraph"><p>A "combined diff" format looks like this:</p></div>

 <div class="listingblock">

 <div class="content">

diff --git a/git-diff-index.html b/git-diff-index.html
index 4bae9f60a..0dd638d89 100644
--- a/git-diff-index.html
+++ b/git-diff-index.html
@@ -2405,9 +2405,9 @@ rename to a</code></pre>
 <div class="paragraph"><p>Any diff-generating command can take the <code>-c</code> or <code>--cc</code> option to

 produce a <em>combined diff</em> when showing a merge. This is the default

 format when showing merges with <a href="git-diff.html">git-diff(1)</a> or

-<a href="git-show.html">git-show(1)</a>. Note also that you can give the <code>-m</code> option to any

-of these commands to force generation of diffs with individual parents

-of a merge.</p></div>

+<a href="git-show.html">git-show(1)</a>. Note also that you can give suitable

+<code>--diff-merges</code> option to any of these commands to force generation of

+diffs in specific format.</p></div>

 <div class="paragraph"><p>A "combined diff" format looks like this:</p></div>

 <div class="listingblock">

 <div class="content">

diff --git a/git-diff-tree.html b/git-diff-tree.html
index 99ee11450..79bdeedb9 100644
--- a/git-diff-tree.html
+++ b/git-diff-tree.html
@@ -3620,9 +3620,9 @@ rename to a</code></pre>
 <div class="paragraph"><p>Any diff-generating command can take the <code>-c</code> or <code>--cc</code> option to

 produce a <em>combined diff</em> when showing a merge. This is the default

 format when showing merges with <a href="git-diff.html">git-diff(1)</a> or

-<a href="git-show.html">git-show(1)</a>. Note also that you can give the <code>-m</code> option to any

-of these commands to force generation of diffs with individual parents

-of a merge.</p></div>

+<a href="git-show.html">git-show(1)</a>. Note also that you can give suitable

+<code>--diff-merges</code> option to any of these commands to force generation of

+diffs in specific format.</p></div>

 <div class="paragraph"><p>A "combined diff" format looks like this:</p></div>

 <div class="listingblock">

 <div class="content">

diff --git a/git-diff.html b/git-diff.html
index 2f44a61b8..68ee0a31c 100644
--- a/git-diff.html
+++ b/git-diff.html
@@ -2540,9 +2540,9 @@ rename to a</code></pre>
 <div class="paragraph"><p>Any diff-generating command can take the <code>-c</code> or <code>--cc</code> option to

 produce a <em>combined diff</em> when showing a merge. This is the default

 format when showing merges with <a href="git-diff.html">git-diff(1)</a> or

-<a href="git-show.html">git-show(1)</a>. Note also that you can give the <code>-m</code> option to any

-of these commands to force generation of diffs with individual parents

-of a merge.</p></div>

+<a href="git-show.html">git-show(1)</a>. Note also that you can give suitable

+<code>--diff-merges</code> option to any of these commands to force generation of

+diffs in specific format.</p></div>

 <div class="paragraph"><p>A "combined diff" format looks like this:</p></div>

 <div class="listingblock">

 <div class="content">

diff --git a/git-log.html b/git-log.html
index dec4cd0d2..10bcde3f4 100644
--- a/git-log.html
+++ b/git-log.html
@@ -1211,6 +1211,11 @@ parents) and <code>--max-parents=-1</code> (negative numbers denote no upper lim
         this option allows you to ignore the individual commits

         brought in to your history by such a merge.

 </p>

+<div class="literalblock">

+<div class="content">

+<pre><code>This option also changes default diff format for merge commits

+to `first-parent`, see `--diff-merges=first-parent` for details.</code></pre>

+</div></div>

 </dd>

 <dt class="hdlist1">

 --not

@@ -3344,99 +3349,141 @@ $ git log -2 --pretty=%h 4da45bef</code></pre>
 <div class="sectionbody">

 <div class="paragraph"><p>By default, <code>git log</code> does not generate any diff output. The options

 below can be used to show the changes made by each commit.</p></div>

-<div class="paragraph"><p>Note that unless one of <code>-c</code>, <code>--cc</code>, or <code>-m</code> is given, merge commits

-will never show a diff, even if a diff format like <code>--patch</code> is

-selected, nor will they match search options like <code>-S</code>. The exception is

-when <code>--first-parent</code> is in use, in which merges are treated like normal

-single-parent commits (this can be overridden by providing a

-combined-diff option or with <code>--no-diff-merges</code>).</p></div>

+<div class="paragraph"><p>Note that unless one of <code>--diff-merges</code> variants (including short

+<code>-m</code>, <code>-c</code>, and <code>--cc</code> options) is explicitly given, merge commits

+will not show a diff, even if a diff format like <code>--patch</code> is

+selected, nor will they match search options like <code>-S</code>. The exception

+is when <code>--first-parent</code> is in use, in which case <code>first-parent</code> is

+the default format.</p></div>

 <div class="dlist"><dl>

 <dt class="hdlist1">

--c

+-p

+</dt>

+<dt class="hdlist1">

+-u

+</dt>

+<dt class="hdlist1">

+--patch

 </dt>

 <dd>

 <p>

-        With this option, diff output for a merge commit

-        shows the differences from each of the parents to the merge result

-        simultaneously instead of showing pairwise diff between a parent

-        and the result one at a time. Furthermore, it lists only files

-        which were modified from all parents.

+        Generate patch (see section on generating patches).

 </p>

 </dd>

 <dt class="hdlist1">

---cc

+-s

+</dt>

+<dt class="hdlist1">

+--no-patch

 </dt>

 <dd>

 <p>

-        This flag implies the <code>-c</code> option and further compresses the

-        patch output by omitting uninteresting hunks whose contents in

-        the parents have only two variants and the merge result picks

-        one of them without modification.

+        Suppress diff output. Useful for commands like <code>git show</code> that

+        show the patch by default, or to cancel the effect of <code>--patch</code>.

 </p>

 </dd>

 <dt class="hdlist1">

---combined-all-paths

+--diff-merges=(off|none|first-parent|1|separate|m|combined|c|dense-combined|cc)

+</dt>

+<dt class="hdlist1">

+--no-diff-merges

 </dt>

 <dd>

 <p>

-        This flag causes combined diffs (used for merge commits) to

-        list the name of the file from all parents.  It thus only has

-        effect when -c or --cc are specified, and is likely only

-        useful if filename changes are detected (i.e. when either

-        rename or copy detection have been requested).

+        Specify diff format to be used for merge commits. Default is

+        <code>off</code> unless <code>--first-parent</code> is in use, in which case

+        <code>first-parent</code> is the default.

+</p>

+<div class="dlist"><dl>

+<dt class="hdlist1">

+--diff-merges=(off|none)

+</dt>

+<dt class="hdlist1">

+--no-diff-merges

+</dt>

+<dd>

+<p>

+        Disable output of diffs for merge commits. Useful to override

+        implied value.

 </p>

 </dd>

 <dt class="hdlist1">

--m

+--diff-merges=first-parent

+</dt>

+<dt class="hdlist1">

+--diff-merges=1

 </dt>

 <dd>

 <p>

-        This flag makes the merge commits show the full diff like

-        regular commits; for each merge parent, a separate log entry

-        and diff is generated. An exception is that only diff against

-        the first parent is shown when <code>--first-parent</code> option is given;

-        in that case, the output represents the changes the merge

-        brought <em>into</em> the then-current branch.

+        This option makes merge commits show the full diff with

+        respect to the first parent only.

 </p>

 </dd>

 <dt class="hdlist1">

---diff-merges=off

+--diff-merges=separate

 </dt>

 <dt class="hdlist1">

---no-diff-merges

+--diff-merges=m

+</dt>

+<dt class="hdlist1">

+-m

 </dt>

 <dd>

 <p>

-        Disable output of diffs for merge commits (default). Useful to

-        override <code>-m</code>, <code>-c</code>, or <code>--cc</code>.

+        This makes merge commits show the full diff with respect to

+        each of the parents. Separate log entry and diff is generated

+        for each parent. <code>-m</code> doesn&#8217;t produce any output without <code>-p</code>.

 </p>

 </dd>

-</dl></div>

-<div class="dlist"><dl>

 <dt class="hdlist1">

--p

+--diff-merges=combined

 </dt>

 <dt class="hdlist1">

--u

+--diff-merges=c

 </dt>

 <dt class="hdlist1">

---patch

+-c

 </dt>

 <dd>

 <p>

-        Generate patch (see section on generating patches).

+        With this option, diff output for a merge commit shows the

+        differences from each of the parents to the merge result

+        simultaneously instead of showing pairwise diff between a

+        parent and the result one at a time. Furthermore, it lists

+        only files which were modified from all parents. <code>-c</code> implies

+        <code>-p</code>.

 </p>

 </dd>

 <dt class="hdlist1">

--s

+--diff-merges=dense-combined

 </dt>

 <dt class="hdlist1">

---no-patch

+--diff-merges=cc

+</dt>

+<dt class="hdlist1">

+--cc

 </dt>

 <dd>

 <p>

-        Suppress diff output. Useful for commands like <code>git show</code> that

-        show the patch by default, or to cancel the effect of <code>--patch</code>.

+        With this option the output produced by

+        <code>--diff-merges=combined</code> is further compressed by omitting

+        uninteresting hunks whose contents in the parents have only

+        two variants and the merge result picks one of them without

+        modification.  <code>--cc</code> implies <code>-p</code>.

+</p>

+</dd>

+</dl></div>

+</dd>

+<dt class="hdlist1">

+--combined-all-paths

+</dt>

+<dd>

+<p>

+        This flag causes combined diffs (used for merge commits) to

+        list the name of the file from all parents.  It thus only has

+        effect when <code>--diff-merges=[dense-]combined</code> is in use, and

+        is likely only useful if filename changes are detected (i.e.

+        when either rename or copy detection have been requested).

 </p>

 </dd>

 <dt class="hdlist1">

@@ -4758,9 +4805,9 @@ rename to a</code></pre>
 <div class="paragraph"><p>Any diff-generating command can take the <code>-c</code> or <code>--cc</code> option to

 produce a <em>combined diff</em> when showing a merge. This is the default

 format when showing merges with <a href="git-diff.html">git-diff(1)</a> or

-<a href="git-show.html">git-show(1)</a>. Note also that you can give the <code>-m</code> option to any

-of these commands to force generation of diffs with individual parents

-of a merge.</p></div>

+<a href="git-show.html">git-show(1)</a>. Note also that you can give suitable

+<code>--diff-merges</code> option to any of these commands to force generation of

+diffs in specific format.</p></div>

 <div class="paragraph"><p>A "combined diff" format looks like this:</p></div>

 <div class="listingblock">

 <div class="content">

@@ -5192,7 +5239,7 @@ and overridden by the <code>--notes=&lt;ref&gt;</code> option.</p></div>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2020-11-18 14:12:24 PST

+ 2021-02-05 17:34:58 PST

 </div>

 </div>

 </body>

diff --git a/git-log.txt b/git-log.txt
index dd189a353..1bbf865a1 100644
--- a/git-log.txt
+++ b/git-log.txt
@@ -107,47 +107,15 @@ DIFF FORMATTING
 By default, `git log` does not generate any diff output. The options
 below can be used to show the changes made by each commit.
 
-Note that unless one of `-c`, `--cc`, or `-m` is given, merge commits
-will never show a diff, even if a diff format like `--patch` is
-selected, nor will they match search options like `-S`. The exception is
-when `--first-parent` is in use, in which merges are treated like normal
-single-parent commits (this can be overridden by providing a
-combined-diff option or with `--no-diff-merges`).
-
--c::
-	With this option, diff output for a merge commit
-	shows the differences from each of the parents to the merge result
-	simultaneously instead of showing pairwise diff between a parent
-	and the result one at a time. Furthermore, it lists only files
-	which were modified from all parents.
-
---cc::
-	This flag implies the `-c` option and further compresses the
-	patch output by omitting uninteresting hunks whose contents in
-	the parents have only two variants and the merge result picks
-	one of them without modification.
-
---combined-all-paths::
-	This flag causes combined diffs (used for merge commits) to
-	list the name of the file from all parents.  It thus only has
-	effect when -c or --cc are specified, and is likely only
-	useful if filename changes are detected (i.e. when either
-	rename or copy detection have been requested).
-
--m::
-	This flag makes the merge commits show the full diff like
-	regular commits; for each merge parent, a separate log entry
-	and diff is generated. An exception is that only diff against
-	the first parent is shown when `--first-parent` option is given;
-	in that case, the output represents the changes the merge
-	brought _into_ the then-current branch.
-
---diff-merges=off::
---no-diff-merges::
-	Disable output of diffs for merge commits (default). Useful to
-	override `-m`, `-c`, or `--cc`.
+Note that unless one of `--diff-merges` variants (including short
+`-m`, `-c`, and `--cc` options) is explicitly given, merge commits
+will not show a diff, even if a diff format like `--patch` is
+selected, nor will they match search options like `-S`. The exception
+is when `--first-parent` is in use, in which case `first-parent` is
+the default format.
 
 :git-log: 1
+:diff-merges-default: `off`
 include::diff-options.txt[]
 
 include::diff-generate-patch.txt[]
diff --git a/git-ls-files.html b/git-ls-files.html
index 063dfa0b3..27c7e3152 100644
--- a/git-ls-files.html
+++ b/git-ls-files.html
@@ -753,6 +753,7 @@ git-ls-files(1) Manual Page
                 (--[cached|deleted|others|ignored|stage|unmerged|killed|modified])*

                 (-[c|d|o|i|s|u|k|m])*

                 [--eol]

+                [--deduplicate]

                 [-x &lt;pattern&gt;|--exclude=&lt;pattern&gt;]

                 [-X &lt;file&gt;|--exclude-from=&lt;file&gt;]

                 [--exclude-per-directory=&lt;file&gt;]

@@ -898,6 +899,18 @@ shown:</p></div>
 </p>

 </dd>

 <dt class="hdlist1">

+--deduplicate

+</dt>

+<dd>

+<p>

+        When only filenames are shown, suppress duplicates that may

+        come from having multiple stages during a merge, or giving

+        <code>--deleted</code> and <code>--modified</code> option at the same time.

+        When any of the <code>-t</code>, <code>--unmerged</code>, or <code>--stage</code> option is

+        in use, this option has no effect.

+</p>

+</dd>

+<dt class="hdlist1">

 -x &lt;pattern&gt;

 </dt>

 <dt class="hdlist1">

@@ -1218,7 +1231,7 @@ pattern file appears in.</p></div>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-01-25 15:29:19 PST

+ 2021-02-05 17:34:58 PST

 </div>

 </div>

 </body>

diff --git a/git-ls-files.txt b/git-ls-files.txt
index 0a3b5265b..6d11ab506 100644
--- a/git-ls-files.txt
+++ b/git-ls-files.txt
@@ -13,6 +13,7 @@ SYNOPSIS
 		(--[cached|deleted|others|ignored|stage|unmerged|killed|modified])*
 		(-[c|d|o|i|s|u|k|m])*
 		[--eol]
+		[--deduplicate]
 		[-x <pattern>|--exclude=<pattern>]
 		[-X <file>|--exclude-from=<file>]
 		[--exclude-per-directory=<file>]
@@ -80,6 +81,13 @@ OPTIONS
 	\0 line termination on output and do not quote filenames.
 	See OUTPUT below for more information.
 
+--deduplicate::
+	When only filenames are shown, suppress duplicates that may
+	come from having multiple stages during a merge, or giving
+	`--deleted` and `--modified` option at the same time.
+	When any of the `-t`, `--unmerged`, or `--stage` option is
+	in use, this option has no effect.
+
 -x <pattern>::
 --exclude=<pattern>::
 	Skip untracked files matching pattern.
diff --git a/git-show.html b/git-show.html
index a66789c0c..f693150b1 100644
--- a/git-show.html
+++ b/git-show.html
@@ -1874,8 +1874,10 @@ $ git log -2 --pretty=%h 4da45bef</code></pre>
 </div>

 </div>

 <div class="sect1">

-<h2 id="_common_diff_options">COMMON DIFF OPTIONS</h2>

+<h2 id="_diff_formatting">DIFF FORMATTING</h2>

 <div class="sectionbody">

+<div class="paragraph"><p>The options below can be used to change the way <code>git show</code> generates

+diff output.</p></div>

 <div class="dlist"><dl>

 <dt class="hdlist1">

 -p

@@ -1904,6 +1906,110 @@ $ git log -2 --pretty=%h 4da45bef</code></pre>
 </p>

 </dd>

 <dt class="hdlist1">

+--diff-merges=(off|none|first-parent|1|separate|m|combined|c|dense-combined|cc)

+</dt>

+<dt class="hdlist1">

+--no-diff-merges

+</dt>

+<dd>

+<p>

+        Specify diff format to be used for merge commits. Default is

+        <code>dense-combined</code> unless <code>--first-parent</code> is in use, in which case

+        <code>first-parent</code> is the default.

+</p>

+<div class="dlist"><dl>

+<dt class="hdlist1">

+--diff-merges=(off|none)

+</dt>

+<dt class="hdlist1">

+--no-diff-merges

+</dt>

+<dd>

+<p>

+        Disable output of diffs for merge commits. Useful to override

+        implied value.

+</p>

+</dd>

+<dt class="hdlist1">

+--diff-merges=first-parent

+</dt>

+<dt class="hdlist1">

+--diff-merges=1

+</dt>

+<dd>

+<p>

+        This option makes merge commits show the full diff with

+        respect to the first parent only.

+</p>

+</dd>

+<dt class="hdlist1">

+--diff-merges=separate

+</dt>

+<dt class="hdlist1">

+--diff-merges=m

+</dt>

+<dt class="hdlist1">

+-m

+</dt>

+<dd>

+<p>

+        This makes merge commits show the full diff with respect to

+        each of the parents. Separate log entry and diff is generated

+        for each parent. <code>-m</code> doesn&#8217;t produce any output without <code>-p</code>.

+</p>

+</dd>

+<dt class="hdlist1">

+--diff-merges=combined

+</dt>

+<dt class="hdlist1">

+--diff-merges=c

+</dt>

+<dt class="hdlist1">

+-c

+</dt>

+<dd>

+<p>

+        With this option, diff output for a merge commit shows the

+        differences from each of the parents to the merge result

+        simultaneously instead of showing pairwise diff between a

+        parent and the result one at a time. Furthermore, it lists

+        only files which were modified from all parents. <code>-c</code> implies

+        <code>-p</code>.

+</p>

+</dd>

+<dt class="hdlist1">

+--diff-merges=dense-combined

+</dt>

+<dt class="hdlist1">

+--diff-merges=cc

+</dt>

+<dt class="hdlist1">

+--cc

+</dt>

+<dd>

+<p>

+        With this option the output produced by

+        <code>--diff-merges=combined</code> is further compressed by omitting

+        uninteresting hunks whose contents in the parents have only

+        two variants and the merge result picks one of them without

+        modification.  <code>--cc</code> implies <code>-p</code>.

+</p>

+</dd>

+</dl></div>

+</dd>

+<dt class="hdlist1">

+--combined-all-paths

+</dt>

+<dd>

+<p>

+        This flag causes combined diffs (used for merge commits) to

+        list the name of the file from all parents.  It thus only has

+        effect when <code>--diff-merges=[dense-]combined</code> is in use, and

+        is likely only useful if filename changes are detected (i.e.

+        when either rename or copy detection have been requested).

+</p>

+</dd>

+<dt class="hdlist1">

 -U&lt;n&gt;

 </dt>

 <dt class="hdlist1">

@@ -3222,9 +3328,9 @@ rename to a</code></pre>
 <div class="paragraph"><p>Any diff-generating command can take the <code>-c</code> or <code>--cc</code> option to

 produce a <em>combined diff</em> when showing a merge. This is the default

 format when showing merges with <a href="git-diff.html">git-diff(1)</a> or

-<a href="git-show.html">git-show(1)</a>. Note also that you can give the <code>-m</code> option to any

-of these commands to force generation of diffs with individual parents

-of a merge.</p></div>

+<a href="git-show.html">git-show(1)</a>. Note also that you can give suitable

+<code>--diff-merges</code> option to any of these commands to force generation of

+diffs in specific format.</p></div>

 <div class="paragraph"><p>A "combined diff" format looks like this:</p></div>

 <div class="listingblock">

 <div class="content">

@@ -3509,7 +3615,7 @@ reversible operation.</p></div>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2020-03-10 08:03:13 PDT

+ 2021-02-05 17:34:58 PST

 </div>

 </div>

 </body>

diff --git a/git-show.txt b/git-show.txt
index fcf528c1b..2b1bc7288 100644
--- a/git-show.txt
+++ b/git-show.txt
@@ -45,10 +45,13 @@ include::pretty-options.txt[]
 include::pretty-formats.txt[]
 
 
-COMMON DIFF OPTIONS
--------------------
+DIFF FORMATTING
+---------------
+The options below can be used to change the way `git show` generates
+diff output.
 
 :git-log: 1
+:diff-merges-default: `dense-combined`
 include::diff-options.txt[]
 
 include::diff-generate-patch.txt[]
diff --git a/howto/keep-canonical-history-correct.html b/howto/keep-canonical-history-correct.html
index 65bf1cf75..da3bb1760 100644
--- a/howto/keep-canonical-history-correct.html
+++ b/howto/keep-canonical-history-correct.html
@@ -938,7 +938,7 @@ tip of your <em>master</em> again and redo the two merges:</p></div>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-02-03 16:01:09 PST

+ 2021-02-05 17:35:49 PST

 </div>

 </div>

 </body>

diff --git a/howto/maintain-git.html b/howto/maintain-git.html
index 0a591e639..d6d5bc9a1 100644
--- a/howto/maintain-git.html
+++ b/howto/maintain-git.html
@@ -1469,7 +1469,7 @@ $ git update-ref -d $mf/ai/topic</code></pre>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-02-03 16:01:09 PST

+ 2021-02-05 17:35:49 PST

 </div>

 </div>

 </body>

diff --git a/howto/new-command.html b/howto/new-command.html
index 6a2721421..c2d8a82f4 100644
--- a/howto/new-command.html
+++ b/howto/new-command.html
@@ -863,7 +863,7 @@ letter [PATCH 0/n].
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-02-03 16:01:05 PST

+ 2021-02-05 17:35:46 PST

 </div>

 </div>

 </body>

diff --git a/howto/rebase-from-internal-branch.html b/howto/rebase-from-internal-branch.html
index d813d3c38..de87c1353 100644
--- a/howto/rebase-from-internal-branch.html
+++ b/howto/rebase-from-internal-branch.html
@@ -895,7 +895,7 @@ the #1' commit.</p></div>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-02-03 16:01:08 PST

+ 2021-02-05 17:35:49 PST

 </div>

 </div>

 </body>

diff --git a/howto/rebuild-from-update-hook.html b/howto/rebuild-from-update-hook.html
index 79781a677..1212dab4e 100644
--- a/howto/rebuild-from-update-hook.html
+++ b/howto/rebuild-from-update-hook.html
@@ -847,7 +847,7 @@ This is still crude and does not protect against simultaneous
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-02-03 16:01:08 PST

+ 2021-02-05 17:35:49 PST

 </div>

 </div>

 </body>

diff --git a/howto/recover-corrupted-blob-object.html b/howto/recover-corrupted-blob-object.html
index 1a74e898a..f9c143872 100644
--- a/howto/recover-corrupted-blob-object.html
+++ b/howto/recover-corrupted-blob-object.html
@@ -880,7 +880,7 @@ thing.</p></div>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-02-03 16:01:08 PST

+ 2021-02-05 17:35:48 PST

 </div>

 </div>

 </body>

diff --git a/howto/recover-corrupted-object-harder.html b/howto/recover-corrupted-object-harder.html
index 981f7363e..648ac4e62 100644
--- a/howto/recover-corrupted-object-harder.html
+++ b/howto/recover-corrupted-object-harder.html
@@ -1189,7 +1189,7 @@ int main(int argc, char **argv)
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-02-03 16:01:08 PST

+ 2021-02-05 17:35:48 PST

 </div>

 </div>

 </body>

diff --git a/howto/revert-a-faulty-merge.html b/howto/revert-a-faulty-merge.html
index 073b401e2..5d274effc 100644
--- a/howto/revert-a-faulty-merge.html
+++ b/howto/revert-a-faulty-merge.html
@@ -1025,7 +1025,7 @@ P---o---o---M---x---x---W---x---M2
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-02-03 16:01:07 PST

+ 2021-02-05 17:35:48 PST

 </div>

 </div>

 </body>

diff --git a/howto/revert-branch-rebase.html b/howto/revert-branch-rebase.html
index 15b4395e4..6e2382928 100644
--- a/howto/revert-branch-rebase.html
+++ b/howto/revert-branch-rebase.html
@@ -907,7 +907,7 @@ Committed merge 7fb9b7262a1d1e0a47bbfdcbbcf50ce0635d3f8f
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-02-03 16:01:05 PST

+ 2021-02-05 17:35:46 PST

 </div>

 </div>

 </body>

diff --git a/howto/separating-topic-branches.html b/howto/separating-topic-branches.html
index 68888a27d..bd565bc30 100644
--- a/howto/separating-topic-branches.html
+++ b/howto/separating-topic-branches.html
@@ -841,7 +841,7 @@ o---o"master"</code></pre>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-02-03 16:01:07 PST

+ 2021-02-05 17:35:48 PST

 </div>

 </div>

 </body>

diff --git a/howto/setup-git-server-over-http.html b/howto/setup-git-server-over-http.html
index 0170316b3..af4915335 100644
--- a/howto/setup-git-server-over-http.html
+++ b/howto/setup-git-server-over-http.html
@@ -1071,7 +1071,7 @@ help diagnosing the problem, but removes security checks.</p></div>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-02-03 16:01:07 PST

+ 2021-02-05 17:35:47 PST

 </div>

 </div>

 </body>

diff --git a/howto/update-hook-example.html b/howto/update-hook-example.html
index 9719eb4b7..d63b710f0 100644
--- a/howto/update-hook-example.html
+++ b/howto/update-hook-example.html
@@ -930,7 +930,7 @@ that JC can make non-fast-forward pushes on it.</p></div>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-02-03 16:01:07 PST

+ 2021-02-05 17:35:47 PST

 </div>

 </div>

 </body>

diff --git a/howto/use-git-daemon.html b/howto/use-git-daemon.html
index 990dc369b..81f938aba 100644
--- a/howto/use-git-daemon.html
+++ b/howto/use-git-daemon.html
@@ -791,7 +791,7 @@ a good practice to put the paths after a "--" separator.</p></div>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-02-03 16:01:06 PST

+ 2021-02-05 17:35:47 PST

 </div>

 </div>

 </body>

diff --git a/howto/using-merge-subtree.html b/howto/using-merge-subtree.html
index e128a912c..f27bfe7de 100644
--- a/howto/using-merge-subtree.html
+++ b/howto/using-merge-subtree.html
@@ -848,7 +848,7 @@ Please note that if the other project merges from you, then it will
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-02-03 16:01:06 PST

+ 2021-02-05 17:35:46 PST

 </div>

 </div>

 </body>

diff --git a/howto/using-signed-tag-in-pull-request.html b/howto/using-signed-tag-in-pull-request.html
index db3cc77e4..2b410d247 100644
--- a/howto/using-signed-tag-in-pull-request.html
+++ b/howto/using-signed-tag-in-pull-request.html
@@ -952,7 +952,7 @@ as part of the merge commit.</p></div>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2021-02-03 16:01:06 PST

+ 2021-02-05 17:35:46 PST

 </div>

 </div>

 </body>

diff --git a/rev-list-options.txt b/rev-list-options.txt
index 002379056..96cc89d15 100644
--- a/rev-list-options.txt
+++ b/rev-list-options.txt
@@ -130,6 +130,11 @@ parents) and `--max-parents=-1` (negative numbers denote no upper limit).
 	this option allows you to ignore the individual commits
 	brought in to your history by such a merge.
 
+ifdef::git-log[]
+	This option also changes default diff format for merge commits
+	to `first-parent`, see `--diff-merges=first-parent` for details.
+endif::git-log[]
+
 --not::
 	Reverses the meaning of the '{caret}' prefix (or lack thereof)
 	for all following revision specifiers, up to the next `--not`.
diff --git a/technical/index-format.html b/technical/index-format.html
index eb8c11d13..79a1431a4 100644
--- a/technical/index-format.html
+++ b/technical/index-format.html
@@ -784,7 +784,7 @@ be ignored if Git does not understand them.</code></pre>
 </div></div>

 <div class="literalblock">

 <div class="content">

-<pre><code>Git currently supports cached tree and resolve undo extensions.</code></pre>

+<pre><code>Git currently supports cache tree and resolve undo extensions.</code></pre>

 </div></div>

 <div class="literalblock">

 <div class="content">

@@ -974,17 +974,42 @@ different. See below for details.</code></pre>
 <h2 id="_extensions">Extensions</h2>

 <div class="sectionbody">

 <div class="sect2">

-<h3 id="_cached_tree">Cached tree</h3>

+<h3 id="_cache_tree">Cache tree</h3>

 <div class="literalblock">

 <div class="content">

-<pre><code>Cached tree extension contains pre-computed hashes for trees that can

-be derived from the index. It helps speed up tree object generation

-from index for a new commit.</code></pre>

+<pre><code>Since the index does not record entries for directories, the cache

+entries cannot describe tree objects that already exist in the object

+database for regions of the index that are unchanged from an existing

+commit. The cache tree extension stores a recursive tree structure that

+describes the trees that already exist and completely match sections of

+the cache entries. This speeds up tree object generation from the index

+for a new commit by only computing the trees that are "new" to that

+commit. It also assists when comparing the index to another tree, such

+as `HEAD^{tree}`, since sections of the index can be skipped when a tree

+comparison demonstrates equality.</code></pre>

 </div></div>

 <div class="literalblock">

 <div class="content">

-<pre><code>When a path is updated in index, the path must be invalidated and

-removed from tree cache.</code></pre>

+<pre><code>The recursive tree structure uses nodes that store a number of cache

+entries, a list of subnodes, and an object ID (OID). The OID references

+the existing tree for that node, if it is known to exist. The subnodes

+correspond to subdirectories that themselves have cache tree nodes. The

+number of cache entries corresponds to the number of cache entries in

+the index that describe paths within that tree's directory.</code></pre>

+</div></div>

+<div class="literalblock">

+<div class="content">

+<pre><code>The extension tracks the full directory structure in the cache tree

+extension, but this is generally smaller than the full cache entry list.</code></pre>

+</div></div>

+<div class="literalblock">

+<div class="content">

+<pre><code>When a path is updated in index, Git invalidates all nodes of the

+recursive cache tree corresponding to the parent directories of that

+path. We store these tree nodes as being "invalid" by using "-1" as the

+number of cache entries. Invalid nodes still store a span of index

+entries, allowing Git to focus its efforts when reconstructing a full

+cache tree.</code></pre>

 </div></div>

 <div class="literalblock">

 <div class="content">

@@ -1041,7 +1066,8 @@ When writing an invalid entry, -1 should always be used as entry_count.</code></
 first entry represents the root level of the repository, followed by the

 first subtree--let's call this A--of the root level (with its name

 relative to the root level), followed by the first subtree of A (with

-its name relative to A), ...</code></pre>

+its name relative to A), and so on. The specified number of subtrees

+indicates when the current level of the recursive stack is complete.</code></pre>

 </div></div>

 </li>

 </ul></div>

@@ -1412,7 +1438,7 @@ A number of index offset entries each consisting of:
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2020-12-17 15:41:40 PST

+ 2021-02-05 17:34:58 PST

 </div>

 </div>

 </body>

diff --git a/technical/index-format.txt b/technical/index-format.txt
index 69edf46c0..b633482b1 100644
--- a/technical/index-format.txt
+++ b/technical/index-format.txt
@@ -26,7 +26,7 @@ Git index format
      Extensions are identified by signature. Optional extensions can
      be ignored if Git does not understand them.
 
-     Git currently supports cached tree and resolve undo extensions.
+     Git currently supports cache tree and resolve undo extensions.
 
      4-byte extension signature. If the first byte is 'A'..'Z' the
      extension is optional and can be ignored.
@@ -136,14 +136,35 @@ Git index format
 
 == Extensions
 
-=== Cached tree
-
-  Cached tree extension contains pre-computed hashes for trees that can
-  be derived from the index. It helps speed up tree object generation
-  from index for a new commit.
-
-  When a path is updated in index, the path must be invalidated and
-  removed from tree cache.
+=== Cache tree
+
+  Since the index does not record entries for directories, the cache
+  entries cannot describe tree objects that already exist in the object
+  database for regions of the index that are unchanged from an existing
+  commit. The cache tree extension stores a recursive tree structure that
+  describes the trees that already exist and completely match sections of
+  the cache entries. This speeds up tree object generation from the index
+  for a new commit by only computing the trees that are "new" to that
+  commit. It also assists when comparing the index to another tree, such
+  as `HEAD^{tree}`, since sections of the index can be skipped when a tree
+  comparison demonstrates equality.
+
+  The recursive tree structure uses nodes that store a number of cache
+  entries, a list of subnodes, and an object ID (OID). The OID references
+  the existing tree for that node, if it is known to exist. The subnodes
+  correspond to subdirectories that themselves have cache tree nodes. The
+  number of cache entries corresponds to the number of cache entries in
+  the index that describe paths within that tree's directory.
+
+  The extension tracks the full directory structure in the cache tree
+  extension, but this is generally smaller than the full cache entry list.
+
+  When a path is updated in index, Git invalidates all nodes of the
+  recursive cache tree corresponding to the parent directories of that
+  path. We store these tree nodes as being "invalid" by using "-1" as the
+  number of cache entries. Invalid nodes still store a span of index
+  entries, allowing Git to focus its efforts when reconstructing a full
+  cache tree.
 
   The signature for this extension is { 'T', 'R', 'E', 'E' }.
 
@@ -174,7 +195,8 @@ Git index format
   first entry represents the root level of the repository, followed by the
   first subtree--let's call this A--of the root level (with its name
   relative to the root level), followed by the first subtree of A (with
-  its name relative to A), ...
+  its name relative to A), and so on. The specified number of subtrees
+  indicates when the current level of the recursive stack is complete.
 
 === Resolve undo