[PATCH 2/9] docs: update offset order for pack index v3
- From
brian m. carlson <sandals@crustytoothpaste.net>
- Date
- Sep 19, 2025, 01:09 UTC
- Message-ID
- <20250919010911.649831-3-sandals@crustytoothpaste.net>
- In-Reply-To
- <20250919010911.649831-1-sandals@crustytoothpaste.net>
The current design of pack index v3 has items in two different orders: sorted shortened object ID order and pack order. The shortened object IDs and the pack index offset values are in the former order and everything else is in the latter.
This, however, poses some problems. We have many parts of the packfile code that expect to find out data about an object knowing only its index in pack order. With the current design, to find the pack offset after having looked up the index in pack order, we must then look up the full object ID and use that to look up the shortened object ID to find the pack offset, which is inconvenient, inefficient, and leads to poor cache usage.
Instead, let's change the offset values to be looked up by pack order. This works better because once we know the pack order offset, we can find the full object name and its location in the pack with a simple index into their respective tables. This makes many operations much more efficient, especially with the functions we already have, and it avoids the need for the revindex with pack index v3.
Signed-off-by: brian m. carlson <sandals@crustytoothpaste.net> --- Documentation/technical/hash-function-transition.adoc | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-)
diff --git a/Documentation/technical/hash-function-transition.adoc b/Documentation/technical/hash-function-transition.adoc index f2df1d618d..11c4f2950a 100644 --- a/Documentation/technical/hash-function-transition.adoc +++ b/Documentation/technical/hash-function-transition.adoc @@ -260,12 +260,10 @@ network byte order): compressed data to be copied directly from pack to pack during repacking without undetected data corruption. - * A table of 4-byte offset values. For an object in the table of - sorted shortened object names, the value at the corresponding - index in this table indicates where that object can be found in - the pack file. These are usually 31-bit pack file offsets, but - large offsets are encoded as an index into the next table with the - most significant bit set. + * A table of 4-byte offset values. The index of this table in pack order + indicates where that object can be found in the pack file. These are + usually 31-bit pack file offsets, but large offsets are encoded as + an index into the next table with the most significant bit set. * A table of 8-byte offset entries (empty for pack files less than 2 GiB). Pack files are organized with heavily used objects toward