Autogenerated HTML docs for v2.49.0-221-g485f5
diff --git a/RelNotes/2.50.0.adoc b/RelNotes/2.50.0.adoc
index 732335c..b787dce 100644
--- a/RelNotes/2.50.0.adoc
+++ b/RelNotes/2.50.0.adoc
@@ -10,6 +10,11 @@
* "git repack" learned "--combine-cruft-below-size" option that
controls how cruft-packs are combined.
+ * TCP keepalive behaviour on http transports can now be configured by
+ calling cURL library.
+
+ * Incrementally updating multi-pack index files.
+
Performance, Internal Implementation, Development Support etc.
--------------------------------------------------------------
@@ -37,8 +42,18 @@
* Enable -Wunreachable-code for developer builds.
- * Build update.
- (merge 7c8cd9c158 es/meson-building-docs-requires-perl later to maint).
+ * Ensure what we write in assert() does not have side effects,
+ and introduce ASSERT() macro to mark those that cannot be
+ mechanically checked for lack of side effects.
+
+ * Give more meaningful error return values from block writer layer of
+ the reftable ref-API backend.
+
+ * Make the code in reftable library less reliant on the service
+ routines it used to borrow from Git proper, to make it easier to
+ use by external users of the library.
+
+ * CI update.
Fixes since v2.49
@@ -88,6 +103,10 @@
* "Dubious ownership" checks on Windows has been tightened up.
(merge 5bb88e89ef js/mingw-admins-are-special later to maint).
+ * Layout configuration in vimdiff backend didn't work as advertised,
+ which has been corrected.
+ (merge 93bab2d04b fr/vimdiff-layout-fixes later to maint).
+
* Other code cleanup, docfix, build fix, etc.
(merge 227c4f33a0 ja/doc-block-delimiter-markup-fix later to maint).
(merge 2bfd3b3685 ab/decorate-code-cleanup later to maint).
@@ -101,3 +120,7 @@
(merge ee434e1807 pw/doc-pack-refs-markup-fix later to maint).
(merge c000918eb7 tb/bitamp-typofix later to maint).
(merge fa8cd29676 js/imap-send-peer-cert-verify later to maint).
+ (merge 98b423bc1c rs/clear-commit-marks-simplify later to maint).
+ (merge 133d065dd6 ta/bulk-checkin-signed-compare-false-warning-fix later to maint).
+ (merge d2827dc31e es/meson-build-skip-coccinelle later to maint).
+ (merge ee8edb7156 dk/vimdiff-doc-fix later to maint).
diff --git a/git-config.html b/git-config.html
index 8b72781..1de473d 100644
--- a/git-config.html
+++ b/git-config.html
@@ -6146,6 +6146,27 @@
Can be overridden by the <code>GIT_HTTP_LOW_SPEED_LIMIT</code> and
<code>GIT_HTTP_LOW_SPEED_TIME</code> environment variables.</p>
</dd>
+<dt class="hdlist1">http.keepAliveIdle</dt>
+<dd>
+<p>Specifies how long in seconds to wait on an idle connection
+before sending TCP keepalive probes (if supported by the OS). If
+unset, curl’s default value is used. Can be overridden by the
+<code>GIT_HTTP_KEEPALIVE_IDLE</code> environment variable.</p>
+</dd>
+<dt class="hdlist1">http.keepAliveInterval</dt>
+<dd>
+<p>Specifies how long in seconds to wait between TCP keepalive
+probes (if supported by the OS). If unset, curl’s default value
+is used. Can be overridden by the <code>GIT_HTTP_KEEPALIVE_INTERVAL</code>
+environment variable.</p>
+</dd>
+<dt class="hdlist1">http.keepAliveCount</dt>
+<dd>
+<p>Specifies how many TCP keepalive probes to send before giving up
+and terminating the connection (if supported by the OS). If
+unset, curl’s default value is used. Can be overridden by the
+<code>GIT_HTTP_KEEPALIVE_COUNT</code> environment variable.</p>
+</dd>
<dt class="hdlist1">http.noEPSV</dt>
<dd>
<p>A boolean which disables using of EPSV ftp command by curl.
diff --git a/git-mergetool.html b/git-mergetool.html
index 491b005..2999d03 100644
--- a/git-mergetool.html
+++ b/git-mergetool.html
@@ -850,7 +850,7 @@
<div class="content">
<div class="paragraph">
<p>When <code>MERGED</code> is not present in the layout, you must "mark" one of the
-buffers with an asterisk. That will become the buffer you need to edit and
+buffers with an arobase (<code>@</code>). That will become the buffer you need to edit and
save after resolving the conflicts.</p>
</div>
<div class="literalblock">
diff --git a/technical/multi-pack-index.adoc b/technical/multi-pack-index.adoc
index cc063b3..ffda70a 100644
--- a/technical/multi-pack-index.adoc
+++ b/technical/multi-pack-index.adoc
@@ -164,19 +164,81 @@
(in the C implementation, this is often computed as `i +
m->num_objects_in_base`).
+=== Pseudo-pack order for incremental MIDXs
+
+The original implementation of multi-pack reachability bitmaps defined
+the pseudo-pack order in linkgit:gitformat-pack[5] (see the section
+titled "multi-pack-index reverse indexes") roughly as follows:
+
+____
+In short, a MIDX's pseudo-pack is the de-duplicated concatenation of
+objects in packs stored by the MIDX, laid out in pack order, and the
+packs arranged in MIDX order (with the preferred pack coming first).
+____
+
+In the incremental MIDX design, we extend this definition to include
+objects from multiple layers of the MIDX chain. The pseudo-pack order
+for incremental MIDXs is determined by concatenating the pseudo-pack
+ordering for each layer of the MIDX chain in order. Formally two objects
+`o1` and `o2` are compared as follows:
+
+1. If `o1` appears in an earlier layer of the MIDX chain than `o2`, then
+ `o1` sorts ahead of `o2`.
+
+2. Otherwise, if `o1` and `o2` appear in the same MIDX layer, and that
+ MIDX layer has no base, then if one of `pack(o1)` and `pack(o2)` is
+ preferred and the other is not, then the preferred one sorts ahead of
+ the non-preferred one. If there is a base layer (i.e. the MIDX layer
+ is not the first layer in the chain), then if `pack(o1)` appears
+ earlier in that MIDX layer's pack order, then `o1` sorts ahead of
+ `o2`. Likewise if `pack(o2)` appears earlier, then the opposite is
+ true.
+
+3. Otherwise, `o1` and `o2` appear in the same pack, and thus in the
+ same MIDX layer. Sort `o1` and `o2` by their offset within their
+ containing packfile.
+
+Note that the preferred pack is a property of the MIDX chain, not the
+individual layers themselves. Fundamentally we could introduce a
+per-layer preferred pack, but this is less relevant now that we can
+perform multi-pack reuse across the set of packs in a MIDX.
+
+=== Reachability bitmaps and incremental MIDXs
+
+Each layer of an incremental MIDX chain may have its objects (and the
+objects from any previous layer in the same MIDX chain) represented in
+its own `*.bitmap` file.
+
+The structure of a `*.bitmap` file belonging to an incremental MIDX
+chain is identical to that of a non-incremental MIDX bitmap, or a
+classic single-pack bitmap. Since objects are added to the end of the
+incremental MIDX's pseudo-pack order (see above), it is possible to
+extend a bitmap when appending to the end of a MIDX chain.
+
+(Note: it is possible likewise to compress a contiguous sequence of MIDX
+incremental layers, and their `*.bitmap` files into a single layer and
+`*.bitmap`, but this is not yet implemented.)
+
+The object positions used are global within the pseudo-pack order, so
+subsequent layers will have, for example, `m->num_objects_in_base`
+number of `0` bits in each of their four type bitmaps. This follows from
+the fact that we only write type bitmap entries for objects present in
+the layer immediately corresponding to the bitmap).
+
+Note also that only the bitmap pertaining to the most recent layer in an
+incremental MIDX chain is used to store reachability information about
+the interesting and uninteresting objects in a reachability query.
+Earlier bitmap layers are only used to look up commit and pseudo-merge
+bitmaps from that layer, as well as the type-level bitmaps for objects
+in that layer.
+
+To simplify the implementation, type-level bitmaps are iterated
+simultaneously, and their results are OR'd together to avoid recursively
+calling internal bitmap functions.
+
Future Work
-----------
-- The multi-pack-index allows many packfiles, especially in a context
- where repacking is expensive (such as a very large repo), or
- unexpected maintenance time is unacceptable (such as a high-demand
- build machine). However, the multi-pack-index needs to be rewritten
- in full every time. We can extend the format to be incremental, so
- writes are fast. By storing a small "tip" multi-pack-index that
- points to large "base" MIDX files, we can keep writes fast while
- still reducing the number of binary searches required for object
- lookups.
-
- If the multi-pack-index is extended to store a "stable object order"
(a function Order(hash) = integer that is constant for a given hash,
even as the multi-pack-index is updated) then MIDX bitmaps could be
diff --git a/technical/multi-pack-index.html b/technical/multi-pack-index.html
index 8d9f4a5..469e5a6 100644
--- a/technical/multi-pack-index.html
+++ b/technical/multi-pack-index.html
@@ -673,6 +673,99 @@
<code>m-</code>><code>num_objects_in_base</code>).</p>
</div>
</div>
+<div class="sect2">
+<h3 id="_pseudo_pack_order_for_incremental_midxs">Pseudo-pack order for incremental MIDXs</h3>
+<div class="paragraph">
+<p>The original implementation of multi-pack reachability bitmaps defined
+the pseudo-pack order in <a href="../gitformat-pack.html">gitformat-pack(5)</a> (see the section
+titled "multi-pack-index reverse indexes") roughly as follows:</p>
+</div>
+<div class="quoteblock">
+<blockquote>
+<div class="paragraph">
+<p>In short, a MIDX’s pseudo-pack is the de-duplicated concatenation of
+objects in packs stored by the MIDX, laid out in pack order, and the
+packs arranged in MIDX order (with the preferred pack coming first).</p>
+</div>
+</blockquote>
+</div>
+<div class="paragraph">
+<p>In the incremental MIDX design, we extend this definition to include
+objects from multiple layers of the MIDX chain. The pseudo-pack order
+for incremental MIDXs is determined by concatenating the pseudo-pack
+ordering for each layer of the MIDX chain in order. Formally two objects
+<code>o1</code> and <code>o2</code> are compared as follows:</p>
+</div>
+<div class="olist arabic">
+<ol class="arabic">
+<li>
+<p>If <code>o1</code> appears in an earlier layer of the MIDX chain than <code>o2</code>, then
+<code>o1</code> sorts ahead of <code>o2</code>.</p>
+</li>
+<li>
+<p>Otherwise, if <code>o1</code> and <code>o2</code> appear in the same MIDX layer, and that
+MIDX layer has no base, then if one of <code>pack</code>(<code>o1</code>) and <code>pack</code>(<code>o2</code>) is
+preferred and the other is not, then the preferred one sorts ahead of
+the non-preferred one. If there is a base layer (i.e. the MIDX layer
+is not the first layer in the chain), then if <code>pack</code>(<code>o1</code>) appears
+earlier in that MIDX layer’s pack order, then <code>o1</code> sorts ahead of
+<code>o2</code>. Likewise if <code>pack</code>(<code>o2</code>) appears earlier, then the opposite is
+true.</p>
+</li>
+<li>
+<p>Otherwise, <code>o1</code> and <code>o2</code> appear in the same pack, and thus in the
+same MIDX layer. Sort <code>o1</code> and <code>o2</code> by their offset within their
+containing packfile.</p>
+</li>
+</ol>
+</div>
+<div class="paragraph">
+<p>Note that the preferred pack is a property of the MIDX chain, not the
+individual layers themselves. Fundamentally we could introduce a
+per-layer preferred pack, but this is less relevant now that we can
+perform multi-pack reuse across the set of packs in a MIDX.</p>
+</div>
+</div>
+<div class="sect2">
+<h3 id="_reachability_bitmaps_and_incremental_midxs">Reachability bitmaps and incremental MIDXs</h3>
+<div class="paragraph">
+<p>Each layer of an incremental MIDX chain may have its objects (and the
+objects from any previous layer in the same MIDX chain) represented in
+its own *.<code>bitmap</code> file.</p>
+</div>
+<div class="paragraph">
+<p>The structure of a *.<code>bitmap</code> file belonging to an incremental MIDX
+chain is identical to that of a non-incremental MIDX bitmap, or a
+classic single-pack bitmap. Since objects are added to the end of the
+incremental MIDX’s pseudo-pack order (see above), it is possible to
+extend a bitmap when appending to the end of a MIDX chain.</p>
+</div>
+<div class="paragraph">
+<p>(Note: it is possible likewise to compress a contiguous sequence of MIDX
+incremental layers, and their *.<code>bitmap</code> files into a single layer and
+*.<code>bitmap</code>, but this is not yet implemented.)</p>
+</div>
+<div class="paragraph">
+<p>The object positions used are global within the pseudo-pack order, so
+subsequent layers will have, for example, <code>m-</code>><code>num_objects_in_base</code>
+number of <code>0</code> bits in each of their four type bitmaps. This follows from
+the fact that we only write type bitmap entries for objects present in
+the layer immediately corresponding to the bitmap).</p>
+</div>
+<div class="paragraph">
+<p>Note also that only the bitmap pertaining to the most recent layer in an
+incremental MIDX chain is used to store reachability information about
+the interesting and uninteresting objects in a reachability query.
+Earlier bitmap layers are only used to look up commit and pseudo-merge
+bitmaps from that layer, as well as the type-level bitmaps for objects
+in that layer.</p>
+</div>
+<div class="paragraph">
+<p>To simplify the implementation, type-level bitmaps are iterated
+simultaneously, and their results are OR’d together to avoid recursively
+calling internal bitmap functions.</p>
+</div>
+</div>
</div>
</div>
<div class="sect1">
@@ -681,17 +774,6 @@
<div class="ulist">
<ul>
<li>
-<p>The multi-pack-index allows many packfiles, especially in a context
-where repacking is expensive (such as a very large repo), or
-unexpected maintenance time is unacceptable (such as a high-demand
-build machine). However, the multi-pack-index needs to be rewritten
-in full every time. We can extend the format to be incremental, so
-writes are fast. By storing a small "tip" multi-pack-index that
-points to large "base" MIDX files, we can keep writes fast while
-still reducing the number of binary searches required for object
-lookups.</p>
-</li>
-<li>
<p>If the multi-pack-index is extended to store a "stable object order"
(a function Order(hash) = integer that is constant for a given hash,
even as the multi-pack-index is updated) then MIDX bitmaps could be
@@ -731,7 +813,7 @@
</div>
<div id="footer">
<div id="footer-text">
-Last updated 2025-02-14 21:38:14 -0800
+Last updated 2025-04-08 12:12:27 -0700
</div>
</div>
</body>
