Autogenerated HTML docs for v2.37.3-518-g79f2

2 files changed, 127 insertions, 1 deletions

diff --git a/technical/bitmap-format.html b/technical/bitmap-format.html
index 064d14f25..3a06697df 100644
--- a/technical/bitmap-format.html
+++ b/technical/bitmap-format.html
@@ -854,6 +854,33 @@ BITMAP_OPT_HASH_CACHE (0x4):
 </dd>

 </dl></div>

 </li>

+<li>

+<p>

+</p>

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

+<dt class="hdlist1">

+BITMAP_OPT_LOOKUP_TABLE (0x10): 

+</dt>

+<dd>

+<p>

+                If present, the end of the bitmap file contains a table

+                containing a list of <code>N</code> &lt;commit_pos, offset, xor_row&gt;

+                triplets. The format and meaning of the table is described

+                below.

+</p>

+<div class="admonitionblock">

+<table><tr>

+<td class="icon">

+<div class="title">Note</div>

+</td>

+<td class="content">Unlike the xor_offset used to compress an individual bitmap,

+<code>xor_row</code> stores an <strong>absolute</strong> index into the lookup table, not a location

+relative to the current entry.</td>

+</tr></table>

+</div>

+</dd>

+</dl></div>

+</li>

 </ul></div>

 </dd>

 <dt class="hdlist1">

@@ -1116,12 +1143,72 @@ free to do so, but MUST allocate a new header flag (because comparing
 hashes made under two different schemes would be pointless).</p></div>

 </div>

 </div>

+<div class="sect1">

+<h2 id="_commit_lookup_table">Commit lookup table</h2>

+<div class="sectionbody">

+<div class="paragraph"><p>If the BITMAP_OPT_LOOKUP_TABLE flag is set, the last <code>N * (4 + 8 + 4)</code>

+bytes (preceding the name-hash cache and trailing hash) of the <code>.bitmap</code>

+file contains a lookup table specifying the information needed to get

+the desired bitmap from the entries without parsing previous unnecessary

+bitmaps.</p></div>

+<div class="paragraph"><p>For a <code>.bitmap</code> containing <code>nr_entries</code> reachability bitmaps, the table

+contains a list of <code>nr_entries</code> &lt;commit_pos, offset, xor_row&gt; triplets

+(sorted in the ascending order of <code>commit_pos</code>). The content of i&#8217;th

+triplet is -</p></div>

+<div class="ulist"><ul>

+<li>

+<p>

+</p>

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

+<dt class="hdlist1">

+commit_pos (4 byte integer, network byte order): 

+</dt>

+<dd>

+<p>

+        It stores the object position of a commit (in the midx or pack

+        index).

+</p>

+</dd>

+</dl></div>

+</li>

+<li>

+<p>

+</p>

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

+<dt class="hdlist1">

+offset (8 byte integer, network byte order): 

+</dt>

+<dd>

+<p>

+        The offset from which that commit&#8217;s bitmap can be read.

+</p>

+</dd>

+</dl></div>

+</li>

+<li>

+<p>

+</p>

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

+<dt class="hdlist1">

+xor_row (4 byte integer, network byte order): 

+</dt>

+<dd>

+<p>

+        The position of the triplet whose bitmap is used to compress

+        this one, or <code>0xffffffff</code> if no such bitmap exists.

+</p>

+</dd>

+</dl></div>

+</li>

+</ul></div>

+</div>

+</div>

 </div>

 <div id="footnotes"><hr /></div>

 <div id="footer">

 <div id="footer-text">

 Last updated

- 2022-07-11 16:06:18 PDT

+ 2022-09-05 18:35:54 PDT

 </div>

 </div>

 </body>

diff --git a/technical/bitmap-format.txt b/technical/bitmap-format.txt
index a85f58f51..c2e652b71 100644
--- a/technical/bitmap-format.txt
+++ b/technical/bitmap-format.txt
@@ -72,6 +72,17 @@ MIDXs, both the bit-cache and rev-cache extensions are required.
 	    pack/MIDX. The format and meaning of the name-hash is
 	    described below.
 
+		** {empty}
+		BITMAP_OPT_LOOKUP_TABLE (0x10): :::
+		If present, the end of the bitmap file contains a table
+		containing a list of `N` <commit_pos, offset, xor_row>
+		triplets. The format and meaning of the table is described
+		below.
++
+NOTE: Unlike the xor_offset used to compress an individual bitmap,
+`xor_row` stores an *absolute* index into the lookup table, not a location
+relative to the current entry.
+
 	4-byte entry count (network byte order): ::
 	    The total count of entries (bitmapped commits) in this bitmap index.
 
@@ -216,3 +227,31 @@ Note that this hashing scheme is tied to the BITMAP_OPT_HASH_CACHE flag.
 If implementations want to choose a different hashing scheme, they are
 free to do so, but MUST allocate a new header flag (because comparing
 hashes made under two different schemes would be pointless).
+
+Commit lookup table
+-------------------
+
+If the BITMAP_OPT_LOOKUP_TABLE flag is set, the last `N * (4 + 8 + 4)`
+bytes (preceding the name-hash cache and trailing hash) of the `.bitmap`
+file contains a lookup table specifying the information needed to get
+the desired bitmap from the entries without parsing previous unnecessary
+bitmaps.
+
+For a `.bitmap` containing `nr_entries` reachability bitmaps, the table
+contains a list of `nr_entries` <commit_pos, offset, xor_row> triplets
+(sorted in the ascending order of `commit_pos`). The content of i'th
+triplet is -
+
+	* {empty}
+	commit_pos (4 byte integer, network byte order): ::
+	It stores the object position of a commit (in the midx or pack
+	index).
+
+	* {empty}
+	offset (8 byte integer, network byte order): ::
+	The offset from which that commit's bitmap can be read.
+
+	* {empty}
+	xor_row (4 byte integer, network byte order): ::
+	The position of the triplet whose bitmap is used to compress
+	this one, or `0xffffffff` if no such bitmap exists.