Skip to content

Commit 7422bac

Browse files
spearcegitster
authored andcommitted
Document the hairy gfi_unpack_entry part of fast-import
Junio pointed out this part of fast-import wasn't very clear on initial read, and it took some time for someone who was new to fast-import's "dirty little tricks" to understand how this was even working. So a little bit of commentary in the proper place may help future readers. Signed-off-by: Shawn O. Pearce <spearce@spearce.org> Signed-off-by: Junio C Hamano <gitster@pobox.com>
1 parent bb23fdf commit 7422bac

File tree

1 file changed

+33
-0
lines changed

1 file changed

+33
-0
lines changed

fast-import.c

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1125,14 +1125,47 @@ static int store_object(
11251125
return 0;
11261126
}
11271127

1128+
/* All calls must be guarded by find_object() or find_mark() to
1129+
* ensure the 'struct object_entry' passed was written by this
1130+
* process instance. We unpack the entry by the offset, avoiding
1131+
* the need for the corresponding .idx file. This unpacking rule
1132+
* works because we only use OBJ_REF_DELTA within the packfiles
1133+
* created by fast-import.
1134+
*
1135+
* oe must not be NULL. Such an oe usually comes from giving
1136+
* an unknown SHA-1 to find_object() or an undefined mark to
1137+
* find_mark(). Callers must test for this condition and use
1138+
* the standard read_sha1_file() when it happens.
1139+
*
1140+
* oe->pack_id must not be MAX_PACK_ID. Such an oe is usually from
1141+
* find_mark(), where the mark was reloaded from an existing marks
1142+
* file and is referencing an object that this fast-import process
1143+
* instance did not write out to a packfile. Callers must test for
1144+
* this condition and use read_sha1_file() instead.
1145+
*/
11281146
static void *gfi_unpack_entry(
11291147
struct object_entry *oe,
11301148
unsigned long *sizep)
11311149
{
11321150
enum object_type type;
11331151
struct packed_git *p = all_packs[oe->pack_id];
11341152
if (p == pack_data && p->pack_size < (pack_size + 20)) {
1153+
/* The object is stored in the packfile we are writing to
1154+
* and we have modified it since the last time we scanned
1155+
* back to read a previously written object. If an old
1156+
* window covered [p->pack_size, p->pack_size + 20) its
1157+
* data is stale and is not valid. Closing all windows
1158+
* and updating the packfile length ensures we can read
1159+
* the newly written data.
1160+
*/
11351161
close_pack_windows(p);
1162+
1163+
/* We have to offer 20 bytes additional on the end of
1164+
* the packfile as the core unpacker code assumes the
1165+
* footer is present at the file end and must promise
1166+
* at least 20 bytes within any window it maps. But
1167+
* we don't actually create the footer here.
1168+
*/
11361169
p->pack_size = pack_size + 20;
11371170
}
11381171
return unpack_entry(p, oe->offset, &type, sizep);

0 commit comments

Comments
 (0)