Autogenerated HTML docs for v2.27.0-203-gf402e

23 files changed, 273 insertions, 51 deletions

diff --git a/RelNotes/2.28.0.txt b/RelNotes/2.28.0.txt
index 55903d8d7..b54c6a00d 100644
--- a/RelNotes/2.28.0.txt
+++ b/RelNotes/2.28.0.txt
@@ -22,6 +22,13 @@ UI, Workflows & Features
  * The interface to redact sensitive information in the trace output
    has been simplified.
 
+ * The command line completion (in contrib/) learned to complete
+   options that the "git switch" command takes.
+
+ * "git diff" used to take arguments in random and nonsense range
+   notation, e.g. "git diff A..B C", "git diff A..B C...D", etc.,
+   which has been cleaned up.
+
 
 Performance, Internal Implementation, Development Support etc.
 
@@ -53,6 +60,22 @@ Performance, Internal Implementation, Development Support etc.
  * Workaround breakage in MSVC build, where "curl-config --cflags"
    gives settings appropriate for GCC build.
 
+ * Code clean-up of "git clean" resulted in a fix of recent
+   performance regression.
+
+ * Code clean-up in the codepath that serves "git fetch" continues.
+
+ * "git merge-base --is-ancestor" is taught to take advantage of the
+   commit graph.
+
+ * Rewrite of parts of the scripted "git submodule" Porcelain command
+   continues; this time it is "git submodule set-branch" subcommand's
+   turn.
+
+ * The "fetch/clone" protocol has been updated to allow the server to
+   instruct the clients to grab pre-packaged packfile(s) in addition
+   to the packed object data coming over the wire.
+
 
 Fixes since v2.27
 -----------------
@@ -110,6 +133,13 @@ Fixes since v2.27
  * The effect of sparse checkout settings on submodules is documented.
    (merge e7d7c73249 en/sparse-with-submodule-doc later to maint).
 
+ * Code clean-up around "git branch" with a minor bugfix.
+   (merge dc44639904 dl/branch-cleanup later to maint).
+
+ * A branch name used in a test has been clarified to match what is
+   going on.
+   (merge 08dc26061f pb/t4014-unslave later to maint).
+
  * Other code cleanup, docfix, build fix, etc.
    (merge 2c31a7aa44 jx/pkt-line-doc-count-fix later to maint).
    (merge d63ae31962 cb/t5608-cleanup later to maint).
diff --git a/git-diff.html b/git-diff.html
index dd8c2c3be..d504471ef 100644
--- a/git-diff.html
+++ b/git-diff.html
@@ -751,7 +751,8 @@ git-diff(1) Manual Page
 <div class="verseblock">

 <pre class="content"><em>git diff</em> [&lt;options&gt;] [&lt;commit&gt;] [--] [&lt;path&gt;&#8230;]

 <em>git diff</em> [&lt;options&gt;] --cached [&lt;commit&gt;] [--] [&lt;path&gt;&#8230;]

-<em>git diff</em> [&lt;options&gt;] &lt;commit&gt; &lt;commit&gt; [--] [&lt;path&gt;&#8230;]

+<em>git diff</em> [&lt;options&gt;] &lt;commit&gt; [&lt;commit&gt;&#8230;] &lt;commit&gt; [--] [&lt;path&gt;&#8230;]

+<em>git diff</em> [&lt;options&gt;] &lt;commit&gt;&#8230;&lt;commit&gt; [--] [&lt;path&gt;&#8230;]

 <em>git diff</em> [&lt;options&gt;] &lt;blob&gt; &lt;blob&gt;

 <em>git diff</em> [&lt;options&gt;] --no-index [--] &lt;path&gt; &lt;path&gt;</pre>

 <div class="attribution">

@@ -762,8 +763,9 @@ git-diff(1) Manual Page
 <h2 id="_description">DESCRIPTION</h2>

 <div class="sectionbody">

 <div class="paragraph"><p>Show changes between the working tree and the index or a tree, changes

-between the index and a tree, changes between two trees, changes between

-two blob objects, or changes between two files on disk.</p></div>

+between the index and a tree, changes between two trees, changes resulting

+from a merge, changes between two blob objects, or changes between two

+files on disk.</p></div>

 <div class="dlist"><dl>

 <dt class="hdlist1">

 <em>git diff</em> [&lt;options&gt;] [--] [&lt;path&gt;&#8230;]

@@ -836,6 +838,19 @@ two blob objects, or changes between two files on disk.</p></div>
 </p>

 </dd>

 <dt class="hdlist1">

+<em>git diff</em> [&lt;options&gt;] &lt;commit&gt; [&lt;commit&gt;&#8230;] &lt;commit&gt; [--] [&lt;path&gt;&#8230;]

+</dt>

+<dd>

+<p>

+        This form is to view the results of a merge commit.  The first

+        listed &lt;commit&gt; must be the merge itself; the remaining two or

+        more commits should be its parents.  A convenient way to produce

+        the desired set of revisions is to use the &#94;@ suffix.

+        For instance, if <code>master</code> names a merge commit, <code>git diff master

+        master^@</code> gives the same combined diff as <code>git show master</code>.

+</p>

+</dd>

+<dt class="hdlist1">

 <em>git diff</em> [&lt;options&gt;] &lt;commit&gt;...&lt;commit&gt; [--] [&lt;path&gt;&#8230;]

 </dt>

 <dd>

@@ -2909,7 +2924,8 @@ Output diff in reverse.
 <a href="git-log.html">git-log(1)</a>,

 <a href="gitdiffcore.html">gitdiffcore(7)</a>,

 <a href="git-format-patch.html">git-format-patch(1)</a>,

-<a href="git-apply.html">git-apply(1)</a></p></div>

+<a href="git-apply.html">git-apply(1)</a>,

+<a href="git-show.html">git-show(1)</a></p></div>

 </div>

 </div>

 <div class="sect1">

@@ -2923,7 +2939,7 @@ Output diff in reverse.
 <div id="footer">

 <div id="footer-text">

 Last updated

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

+ 2020-06-25 14:07:29 PDT

 </div>

 </div>

 </body>

diff --git a/git-diff.txt b/git-diff.txt
index 37781cf17..1018110dd 100644
--- a/git-diff.txt
+++ b/git-diff.txt
@@ -11,15 +11,17 @@ SYNOPSIS
 [verse]
 'git diff' [<options>] [<commit>] [--] [<path>...]
 'git diff' [<options>] --cached [<commit>] [--] [<path>...]
-'git diff' [<options>] <commit> <commit> [--] [<path>...]
+'git diff' [<options>] <commit> [<commit>...] <commit> [--] [<path>...]
+'git diff' [<options>] <commit>...<commit> [--] [<path>...]
 'git diff' [<options>] <blob> <blob>
 'git diff' [<options>] --no-index [--] <path> <path>
 
 DESCRIPTION
 -----------
 Show changes between the working tree and the index or a tree, changes
-between the index and a tree, changes between two trees, changes between
-two blob objects, or changes between two files on disk.
+between the index and a tree, changes between two trees, changes resulting
+from a merge, changes between two blob objects, or changes between two
+files on disk.
 
 'git diff' [<options>] [--] [<path>...]::
 
@@ -67,6 +69,15 @@ two blob objects, or changes between two files on disk.
 	one side is omitted, it will have the same effect as
 	using HEAD instead.
 
+'git diff' [<options>] <commit> [<commit>...] <commit> [--] [<path>...]::
+
+	This form is to view the results of a merge commit.  The first
+	listed <commit> must be the merge itself; the remaining two or
+	more commits should be its parents.  A convenient way to produce
+	the desired set of revisions is to use the {caret}@ suffix.
+	For instance, if `master` names a merge commit, `git diff master
+	master^@` gives the same combined diff as `git show master`.
+
 'git diff' [<options>] <commit>\...<commit> [--] [<path>...]::
 
 	This form is to view the changes on the branch containing
@@ -196,7 +207,8 @@ linkgit:git-difftool[1],
 linkgit:git-log[1],
 linkgit:gitdiffcore[7],
 linkgit:git-format-patch[1],
-linkgit:git-apply[1]
+linkgit:git-apply[1],
+linkgit:git-show[1]
 
 GIT
 ---
diff --git a/git-http-fetch.html b/git-http-fetch.html
index f4dc2339f..60f0bcb9c 100644
--- a/git-http-fetch.html
+++ b/git-http-fetch.html
@@ -749,7 +749,7 @@ git-http-fetch(1) Manual Page
 <h2 id="_synopsis">SYNOPSIS</h2>

 <div class="sectionbody">

 <div class="verseblock">

-<pre class="content"><em>git http-fetch</em> [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin] &lt;commit&gt; &lt;url&gt;</pre>

+<pre class="content"><em>git http-fetch</em> [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin | --packfile=&lt;hash&gt; | &lt;commit&gt;] &lt;url&gt;</pre>

 <div class="attribution">

 </div></div>

 </div>

@@ -815,6 +815,18 @@ commit-id
 </div></div>

 </dd>

 <dt class="hdlist1">

+--packfile=&lt;hash&gt;

+</dt>

+<dd>

+<p>

+        Instead of a commit id on the command line (which is not expected in

+        this case), <em>git http-fetch</em> fetches the packfile directly at the given

+        URL and uses index-pack to generate corresponding .idx and .keep files.

+        The hash is used to determine the name of the temporary file and is

+        arbitrary. The output of index-pack is printed to stdout.

+</p>

+</dd>

+<dt class="hdlist1">

 --recover

 </dt>

 <dd>

@@ -837,7 +849,7 @@ commit-id
 <div id="footer">

 <div id="footer-text">

 Last updated

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

+ 2020-06-25 14:07:29 PDT

 </div>

 </div>

 </body>

diff --git a/git-http-fetch.txt b/git-http-fetch.txt
index 666b04267..4deb4893f 100644
--- a/git-http-fetch.txt
+++ b/git-http-fetch.txt
@@ -9,7 +9,7 @@ git-http-fetch - Download from a remote Git repository via HTTP
 SYNOPSIS
 --------
 [verse]
-'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin] <commit> <url>
+'git http-fetch' [-c] [-t] [-a] [-d] [-v] [-w filename] [--recover] [--stdin | --packfile=<hash> | <commit>] <url>
 
 DESCRIPTION
 -----------
@@ -40,6 +40,13 @@ commit-id::
 
 		<commit-id>['\t'<filename-as-in--w>]
 
+--packfile=<hash>::
+	Instead of a commit id on the command line (which is not expected in
+	this case), 'git http-fetch' fetches the packfile directly at the given
+	URL and uses index-pack to generate corresponding .idx and .keep files.
+	The hash is used to determine the name of the temporary file and is
+	arbitrary. The output of index-pack is printed to stdout.
+
 --recover::
 	Verify that everything reachable from target is fetched.  Used after
 	an earlier fetch is interrupted.
diff --git a/howto/keep-canonical-history-correct.html b/howto/keep-canonical-history-correct.html
index f83561d44..246f023ab 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

- 2020-06-22 16:56:44 PDT

+ 2020-06-25 14:08:20 PDT

 </div>

 </div>

 </body>

diff --git a/howto/maintain-git.html b/howto/maintain-git.html
index e0b86e0be..f773f65e3 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

- 2020-06-22 16:56:44 PDT

+ 2020-06-25 14:08:20 PDT

 </div>

 </div>

 </body>

diff --git a/howto/new-command.html b/howto/new-command.html
index 98a5b243f..bffa90178 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

- 2020-06-22 16:56:38 PDT

+ 2020-06-25 14:08:17 PDT

 </div>

 </div>

 </body>

diff --git a/howto/rebase-from-internal-branch.html b/howto/rebase-from-internal-branch.html
index be076eb5c..5dea01b3c 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

- 2020-06-22 16:56:44 PDT

+ 2020-06-25 14:08:20 PDT

 </div>

 </div>

 </body>

diff --git a/howto/rebuild-from-update-hook.html b/howto/rebuild-from-update-hook.html
index 942cbb33f..4f722dd69 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

- 2020-06-22 16:56:43 PDT

+ 2020-06-25 14:08:20 PDT

 </div>

 </div>

 </body>

diff --git a/howto/recover-corrupted-blob-object.html b/howto/recover-corrupted-blob-object.html
index 5010b0f0d..f3419da36 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

- 2020-06-22 16:56:42 PDT

+ 2020-06-25 14:08:19 PDT

 </div>

 </div>

 </body>

diff --git a/howto/recover-corrupted-object-harder.html b/howto/recover-corrupted-object-harder.html
index 24c5bdc1f..acca26f8c 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

- 2020-06-22 16:56:43 PDT

+ 2020-06-25 14:08:20 PDT

 </div>

 </div>

 </body>

diff --git a/howto/revert-a-faulty-merge.html b/howto/revert-a-faulty-merge.html
index 82c656c47..677f2b98a 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

- 2020-06-22 16:56:41 PDT

+ 2020-06-25 14:08:19 PDT

 </div>

 </div>

 </body>

diff --git a/howto/revert-branch-rebase.html b/howto/revert-branch-rebase.html
index 062e1abe5..fd03c16c7 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

- 2020-06-22 16:56:38 PDT

+ 2020-06-25 14:08:17 PDT

 </div>

 </div>

 </body>

diff --git a/howto/separating-topic-branches.html b/howto/separating-topic-branches.html
index 8716082e2..f9aeb04f0 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

- 2020-06-22 16:56:41 PDT

+ 2020-06-25 14:08:19 PDT

 </div>

 </div>

 </body>

diff --git a/howto/setup-git-server-over-http.html b/howto/setup-git-server-over-http.html
index b0652d757..cb529f3e4 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

- 2020-06-22 16:56:40 PDT

+ 2020-06-25 14:08:18 PDT

 </div>

 </div>

 </body>

diff --git a/howto/update-hook-example.html b/howto/update-hook-example.html
index c2087c319..ee1142e31 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

- 2020-06-22 16:56:40 PDT

+ 2020-06-25 14:08:18 PDT

 </div>

 </div>

 </body>

diff --git a/howto/use-git-daemon.html b/howto/use-git-daemon.html
index 114dcad67..46c29d2df 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

- 2020-06-22 16:56:39 PDT

+ 2020-06-25 14:08:18 PDT

 </div>

 </div>

 </body>

diff --git a/howto/using-merge-subtree.html b/howto/using-merge-subtree.html
index e5cc79331..228b5893a 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

- 2020-06-22 16:56:39 PDT

+ 2020-06-25 14:08:17 PDT

 </div>

 </div>

 </body>

diff --git a/howto/using-signed-tag-in-pull-request.html b/howto/using-signed-tag-in-pull-request.html
index c51d6992a..7b1221008 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

- 2020-06-22 16:56:39 PDT

+ 2020-06-25 14:08:18 PDT

 </div>

 </div>

 </body>

diff --git a/technical/packfile-uri.txt b/technical/packfile-uri.txt
new file mode 100644
index 000000000..318713abc
--- /dev/null
+++ b/technical/packfile-uri.txt
@@ -0,0 +1,78 @@
+Packfile URIs
+=============
+
+This feature allows servers to serve part of their packfile response as URIs.
+This allows server designs that improve scalability in bandwidth and CPU usage
+(for example, by serving some data through a CDN), and (in the future) provides
+some measure of resumability to clients.
+
+This feature is available only in protocol version 2.
+
+Protocol
+--------
+
+The server advertises the `packfile-uris` capability.
+
+If the client then communicates which protocols (HTTPS, etc.) it supports with
+a `packfile-uris` argument, the server MAY send a `packfile-uris` section
+directly before the `packfile` section (right after `wanted-refs` if it is
+sent) containing URIs of any of the given protocols. The URIs point to
+packfiles that use only features that the client has declared that it supports
+(e.g. ofs-delta and thin-pack). See protocol-v2.txt for the documentation of
+this section.
+
+Clients should then download and index all the given URIs (in addition to
+downloading and indexing the packfile given in the `packfile` section of the
+response) before performing the connectivity check.
+
+Server design
+-------------
+
+The server can be trivially made compatible with the proposed protocol by
+having it advertise `packfile-uris`, tolerating the client sending
+`packfile-uris`, and never sending any `packfile-uris` section. But we should
+include some sort of non-trivial implementation in the Minimum Viable Product,
+at least so that we can test the client.
+
+This is the implementation: a feature, marked experimental, that allows the
+server to be configured by one or more `uploadpack.blobPackfileUri=<sha1>
+<uri>` entries. Whenever the list of objects to be sent is assembled, all such
+blobs are excluded, replaced with URIs. The client will download those URIs,
+expecting them to each point to packfiles containing single blobs.
+
+Client design
+-------------
+
+The client has a config variable `fetch.uriprotocols` that determines which
+protocols the end user is willing to use. By default, this is empty.
+
+When the client downloads the given URIs, it should store them with "keep"
+files, just like it does with the packfile in the `packfile` section. These
+additional "keep" files can only be removed after the refs have been updated -
+just like the "keep" file for the packfile in the `packfile` section.
+
+The division of work (initial fetch + additional URIs) introduces convenient
+points for resumption of an interrupted clone - such resumption can be done
+after the Minimum Viable Product (see "Future work").
+
+Future work
+-----------
+
+The protocol design allows some evolution of the server and client without any
+need for protocol changes, so only a small-scoped design is included here to
+form the MVP. For example, the following can be done:
+
+ * On the server, more sophisticated means of excluding objects (e.g. by
+   specifying a commit to represent that commit and all objects that it
+   references).
+ * On the client, resumption of clone. If a clone is interrupted, information
+   could be recorded in the repository's config and a "clone-resume" command
+   can resume the clone in progress. (Resumption of subsequent fetches is more
+   difficult because that must deal with the user wanting to use the repository
+   even after the fetch was interrupted.)
+
+There are some possible features that will require a change in protocol:
+
+ * Additional HTTP headers (e.g. authentication)
+ * Byte range support
+ * Different file formats referenced by URIs (e.g. raw object)
diff --git a/technical/protocol-v2.html b/technical/protocol-v2.html
index 4bcfb6ac2..4fd3703e0 100644
--- a/technical/protocol-v2.html
+++ b/technical/protocol-v2.html
@@ -1132,14 +1132,28 @@ included in the client&#8217;s request:</p></div>
     indicating its sideband (1, 2, or 3), and the server may send "0005\2"

     (a PKT-LINE of sideband 2 with no payload) as a keepalive packet.</code></pre>

 </div></div>

+<div class="paragraph"><p>If the <em>packfile-uris</em> feature is advertised, the following argument

+can be included in the client&#8217;s request as well as the potential

+addition of the <em>packfile-uris</em> section in the server&#8217;s response as

+explained below.</p></div>

+<div class="literalblock">

+<div class="content">

+<pre><code>packfile-uris &lt;comma-separated list of protocols&gt;

+    Indicates to the server that the client is willing to receive

+    URIs of any of the given protocols in place of objects in the

+    sent packfile. Before performing the connectivity check, the

+    client should download from all given URIs. Currently, the

+    protocols supported are "http" and "https".</code></pre>

+</div></div>

 <div class="paragraph"><p>The response of <code>fetch</code> is broken into a number of sections separated by

 delimiter packets (0001), with each section beginning with its section

-header.</p></div>

+header. Most sections are sent only when the packfile is sent.</p></div>

 <div class="literalblock">

 <div class="content">

-<pre><code>output = *section

-section = (acknowledgments | shallow-info | wanted-refs | packfile)

-          (flush-pkt | delim-pkt)</code></pre>

+<pre><code>output = acknowledgements flush-pkt |

+         [acknowledgments delim-pkt] [shallow-info delim-pkt]

+         [wanted-refs delim-pkt] [packfile-uris delim-pkt]

+         packfile flush-pkt</code></pre>

 </div></div>

 <div class="literalblock">

 <div class="content">

@@ -1165,15 +1179,21 @@ wanted-ref = obj-id SP refname</code></pre>
 </div></div>

 <div class="literalblock">

 <div class="content">

+<pre><code>packfile-uris = PKT-LINE("packfile-uris" LF) *packfile-uri

+packfile-uri = PKT-LINE(40*(HEXDIGIT) SP *%x20-ff LF)</code></pre>

+</div></div>

+<div class="literalblock">

+<div class="content">

 <pre><code>packfile = PKT-LINE("packfile" LF)

            *PKT-LINE(%x01-03 *%x00-ff)</code></pre>

 </div></div>

 <div class="literalblock">

 <div class="content">

 <pre><code>acknowledgments section

-    * If the client determines that it is finished with negotiations

-      by sending a "done" line, the acknowledgments sections MUST be

-      omitted from the server's response.</code></pre>

+    * If the client determines that it is finished with negotiations by

+      sending a "done" line (thus requiring the server to send a packfile),

+      the acknowledgments sections MUST be omitted from the server's

+      response.</code></pre>

 </div></div>

 <div class="ulist"><ul>

 <li>

@@ -1259,12 +1279,6 @@ The server MUST NOT send any "unshallow" lines for anything
           which the client has not indicated was shallow as a part of

           its request.

 </p>

-</li>

-<li>

-<p>

-This section is only included if a packfile section is also

-          included in the response.

-</p>

 <div class="literalblock">

 <div class="content">

 <pre><code>wanted-refs section

@@ -1291,6 +1305,31 @@ The server MUST NOT send any refs which were not requested
 </p>

 <div class="literalblock">

 <div class="content">

+<pre><code>packfile-uris section

+    * This section is only included if the client sent

+      'packfile-uris' and the server has at least one such URI to

+      send.</code></pre>

+</div></div>

+</li>

+<li>

+<p>

+Always begins with the section header "packfile-uris".

+</p>

+</li>

+<li>

+<p>

+For each URI the server sends, it sends a hash of the pack&#8217;s

+          contents (as output by git index-pack) followed by the URI.

+</p>

+</li>

+<li>

+<p>

+The hashes are 40 hex characters long. When Git upgrades to a new

+          hash algorithm, this might need to be updated. (It should match

+          whatever index-pack outputs after "pack\t" or "keep\t".

+</p>

+<div class="literalblock">

+<div class="content">

 <pre><code>packfile section

     * This section is only included if the client has sent 'want'

       lines in its request and either requested that no more

@@ -1344,7 +1383,7 @@ a request.</p></div>
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2020-06-08 18:30:54 PDT

+ 2020-06-25 14:07:29 PDT

 </div>

 </div>

 </body>

diff --git a/technical/protocol-v2.txt b/technical/protocol-v2.txt
index 3996d7089..5852f499a 100644
--- a/technical/protocol-v2.txt
+++ b/technical/protocol-v2.txt
@@ -325,13 +325,26 @@ included in the client's request:
 	indicating its sideband (1, 2, or 3), and the server may send "0005\2"
 	(a PKT-LINE of sideband 2 with no payload) as a keepalive packet.
 
+If the 'packfile-uris' feature is advertised, the following argument
+can be included in the client's request as well as the potential
+addition of the 'packfile-uris' section in the server's response as
+explained below.
+
+    packfile-uris <comma-separated list of protocols>
+	Indicates to the server that the client is willing to receive
+	URIs of any of the given protocols in place of objects in the
+	sent packfile. Before performing the connectivity check, the
+	client should download from all given URIs. Currently, the
+	protocols supported are "http" and "https".
+
 The response of `fetch` is broken into a number of sections separated by
 delimiter packets (0001), with each section beginning with its section
-header.
+header. Most sections are sent only when the packfile is sent.
 
-    output = *section
-    section = (acknowledgments | shallow-info | wanted-refs | packfile)
-	      (flush-pkt | delim-pkt)
+    output = acknowledgements flush-pkt |
+	     [acknowledgments delim-pkt] [shallow-info delim-pkt]
+	     [wanted-refs delim-pkt] [packfile-uris delim-pkt]
+	     packfile flush-pkt
 
     acknowledgments = PKT-LINE("acknowledgments" LF)
 		      (nak | *ack)
@@ -349,13 +362,17 @@ header.
 		  *PKT-LINE(wanted-ref LF)
     wanted-ref = obj-id SP refname
 
+    packfile-uris = PKT-LINE("packfile-uris" LF) *packfile-uri
+    packfile-uri = PKT-LINE(40*(HEXDIGIT) SP *%x20-ff LF)
+
     packfile = PKT-LINE("packfile" LF)
 	       *PKT-LINE(%x01-03 *%x00-ff)
 
     acknowledgments section
-	* If the client determines that it is finished with negotiations
-	  by sending a "done" line, the acknowledgments sections MUST be
-	  omitted from the server's response.
+	* If the client determines that it is finished with negotiations by
+	  sending a "done" line (thus requiring the server to send a packfile),
+	  the acknowledgments sections MUST be omitted from the server's
+	  response.
 
 	* Always begins with the section header "acknowledgments"
 
@@ -406,9 +423,6 @@ header.
 	  which the client has not indicated was shallow as a part of
 	  its request.
 
-	* This section is only included if a packfile section is also
-	  included in the response.
-
     wanted-refs section
 	* This section is only included if the client has requested a
 	  ref using a 'want-ref' line and if a packfile section is also
@@ -422,6 +436,20 @@ header.
 	* The server MUST NOT send any refs which were not requested
 	  using 'want-ref' lines.
 
+    packfile-uris section
+	* This section is only included if the client sent
+	  'packfile-uris' and the server has at least one such URI to
+	  send.
+
+	* Always begins with the section header "packfile-uris".
+
+	* For each URI the server sends, it sends a hash of the pack's
+	  contents (as output by git index-pack) followed by the URI.
+
+	* The hashes are 40 hex characters long. When Git upgrades to a new
+	  hash algorithm, this might need to be updated. (It should match
+	  whatever index-pack outputs after "pack\t" or "keep\t".
+
     packfile section
 	* This section is only included if the client has sent 'want'
 	  lines in its request and either requested that no more