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>
Shawn O. Pearce committed
Jan 20, 2008 at 23:37 UTC
7422bac441d6e00cfb8302600ae64512837ab4e3
1 file changed
+33
fast-import.c
+33
@@ -1125,6 +1125,24 @@ static int store_object(
1125
return 0;
1126
}
1127
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
+ */
1146
static void *gfi_unpack_entry(
1147
struct object_entry *oe,
1148
unsigned long *sizep)
@@ -1132,7 +1150,22 @@ static void *gfi_unpack_entry(
1150
enum object_type type;
1151
struct packed_git *p = all_packs[oe->pack_id];
1152
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
+ */
1161
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
+ */
1169
p->pack_size = pack_size + 20;
1170
}
1171
return unpack_entry(p, oe->offset, &type, sizep);