git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Docs: possible incorrect diagram of Delta Copy instruction

From
BVBouke Versteegh <info@boukeversteegh.nl>
Date
Sep 11, 2020, 12:30 UTC
Message-ID
<CAFag0172JvkTgzXs2ieq2kSfnNRy_8n5YsP87uQ-Pyf5vB+yfw@mail.gmail.com>
Dear maintainers of git documentation,

While working on an implementation of git in dart, I've noticed a possible error in the documentation. I hope I'm using the correct channel to report this issue.

On [pack format](https://git-scm.com/docs/pack-format#_instruction_to_copy_from_base_object) a diagram is shown, that explains the format of a Copy instruction inside a Deltified pack entry:

+----------+---------+---------+---------+---------+-------+-------+-------+
| 1xxxxxxx | offset1 | offset2 | offset3 | offset4 | size1 | size2 | size3 |
+----------+---------+---------+---------+---------+-------+-------+-------+

The documentation specifies that diagrams follow the RFC950 (https://www.ietf.org/rfc/rfc1950.txt) format. That means that the left bit is MSB, and the right bit is LSB, so the OpCode is MSB (1xxxxxxx), which is correct and matches other sources. It also would mean that offset 1-4 should be read from bit 7, 6, 5 and 4 (i.e. 0x40, 0x20, 0x10, 0x08)

However, looking at the git source-code and other documentation (see [1] [2]), I see that offset [1-4] are read from the LOWEST 4 bits, and the SIZE bits are stored right after MSB (opcode).

https://github.com/git/git/blob/54e85e7af1ac9e9a92888060d6811ae767fea1bc/patch-delta.c#L49-L55
  PARSE_CP_PARAM(0x01, cp_off, 0);
  PARSE_CP_PARAM(0x02, cp_off, 8);
  PARSE_CP_PARAM(0x04, cp_off, 16);
  PARSE_CP_PARAM(0x08, cp_off, 24);
  PARSE_CP_PARAM(0x10, cp_size, 0);
  PARSE_CP_PARAM(0x20, cp_size, 8);
  PARSE_CP_PARAM(0x40, cp_size, 16);

From this source code, I would conclude that the diagram should look like this instead:

+----------+---------+---------+---------+---------+-------+-------+-------+
| 1xxxxxxx | size3 | size 2 | size1 | offset4 | offset3 | offset2 | offset1 |
+----------+---------+---------+---------+---------+-------+-------+-------+
Please let me know if I misunderstood the diagram instead.
Kind regards, Bouke

[1] https://shop.jcoglan.com/building-git/ [2] https://codewords.recurse.com/issues/three/unpacking-git-packfiles#applying-deltas

Next: Jeff King
Message 1 of 3 in “Docs: possible incorrect diagram of Delta Copy instruction”
  1. Bouke VersteeghSep 11, 2020
  2. Jeff KingSep 11, 2020
  3. Bouke VersteeghSep 12, 2020

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.