apply: document buffer ownership rules across functions
In general, the private functions in this file were not very much documented; even though what each of them do is reasonably self explanatory, the ownership rules for various buffers and data structures were not very obvious. Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Apr 11, 2012 at 14:43 UTC
92737a2201f75460dad195474a728dcf8ed79804
1 file changed
+51
-2
builtin/apply.c
+51
-2
@@ -151,6 +151,10 @@ struct fragment {
151
unsigned long leading, trailing;
152
unsigned long oldpos, oldlines;
153
unsigned long newpos, newlines;
154
+ /*
155
+ * 'patch' is usually borrowed from buf in apply_patch(),
156
+ * but some codepaths store an allocated buffer.
157
+ */
158
const char *patch;
159
unsigned free_patch:1,
160
rejected:1;
@@ -332,6 +336,11 @@ static void add_line_info(struct image *img, const char *bol, size_t len, unsign
336
img->nr++;
337
}
338
339
+/*
340
+ * "buf" has the file contents to be patched (read from various sources).
341
+ * attach it to "image" and add line-based index to it.
342
+ * "image" now owns the "buf".
343
+ */
344
static void prepare_image(struct image *image, char *buf, size_t len,
345
int prepare_linetable)
346
{
@@ -1607,6 +1616,14 @@ static int parse_fragment(const char *line, unsigned long size,
1616
return offset;
1617
}
1618
1619
+/*
1620
+ * We have seen "diff --git a/... b/..." header (or a traditional patch
1621
+ * header). Read hunks that belong to this patch into fragments and hang
1622
+ * them to the given patch structure.
1623
+ *
1624
+ * The (fragment->patch, fragment->size) pair points into the memory given
1625
+ * by the caller, not a copy, when we return.
1626
+ */
1627
static int parse_single_patch(const char *line, unsigned long size, struct patch *patch)
1628
{
1629
unsigned long offset = 0;
@@ -1700,6 +1717,11 @@ static char *inflate_it(const void *data, unsigned long size,
1717
return out;
1718
}
1719
1720
+/*
1721
+ * Read a binary hunk and return a new fragment; fragment->patch
1722
+ * points at an allocated memory that the caller must free, so
1723
+ * it is marked as "->free_patch = 1".
1724
+ */
1725
static struct fragment *parse_binary_hunk(char **buf_p,
1726
unsigned long *sz_p,
1727
int *status_p,
@@ -1853,6 +1875,13 @@ static int parse_binary(char *buffer, unsigned long size, struct patch *patch)
1875
return used;
1876
}
1877
1878
+/*
1879
+ * Read the patch text in "buffer" taht extends for "size" bytes; stop
1880
+ * reading after seeing a single patch (i.e. changes to a single file).
1881
+ * Create fragments (i.e. patch hunks) and hang them to the given patch.
1882
+ * Return the number of bytes consumed, so that the caller can call us
1883
+ * again for the next patch.
1884
+ */
1885
static int parse_chunk(char *buffer, unsigned long size, struct patch *patch)
1886
{
1887
int hdrsize, patchsize;
@@ -2413,6 +2442,11 @@ static void remove_last_line(struct image *img)
2442
img->len -= img->line[--img->nr].len;
2443
}
2444
2445
+/*
2446
+ * The change from "preimage" and "postimage" has been found to
2447
+ * apply at applied_pos (counts in line numbers) in "img".
2448
+ * Update "img" to remove "preimage" and replace it with "postimage".
2449
+ */
2450
static void update_image(struct image *img,
2451
int applied_pos,
2452
struct image *preimage,
@@ -2484,6 +2518,11 @@ static void update_image(struct image *img,
2518
img->nr = nr;
2519
}
2520
2521
+/*
2522
+ * Use the patch-hunk text in "frag" to prepare two images (preimage and
2523
+ * postimage) for the hunk. Find lines that match "preimage" in "img" and
2524
+ * replace the part of "img" with "postimage" text.
2525
+ */
2526
static int apply_one_fragment(struct image *img, struct fragment *frag,
2527
int inaccurate_eof, unsigned ws_rule,
2528
int nth_fragment)
@@ -2774,6 +2813,12 @@ static int apply_binary_fragment(struct image *img, struct patch *patch)
2813
return -1;
2814
}
2815
2816
+/*
2817
+ * Replace "img" with the result of applying the binary patch.
2818
+ * The binary patch data itself in patch->fragment is still kept
2819
+ * but the preimage prepared by the caller in "img" is freed here
2820
+ * or in the helper function apply_binary_fragment() this calls.
2821
+ */
2822
static int apply_binary(struct image *img, struct patch *patch)
2823
{
2824
const char *name = patch->old_name ? patch->old_name : patch->new_name;
@@ -2981,7 +3026,7 @@ static int apply_data(struct patch *patch, struct stat *st, struct cache_entry *
3026
return error("patch %s has been renamed/deleted",
3027
patch->old_name);
3028
}
2984
- /* We have a patched copy in memory use that */
3029
+ /* We have a patched copy in memory; use that. */
3030
strbuf_add(&buf, tpatch->result, tpatch->resultsize);
3031
} else if (cached) {
3032
if (read_file_or_gitlink(ce, &buf))
@@ -3139,6 +3184,10 @@ static int check_preimage(struct patch *patch, struct cache_entry **ce, struct s
3184
return 0;
3185
}
3186
3187
+/*
3188
+ * Check and apply the patch in-core; leave the result in patch->result
3189
+ * for the caller to write it out to the final destination.
3190
+ */
3191
static int check_patch(struct patch *patch)
3192
{
3193
struct stat st;
@@ -3726,7 +3775,7 @@ static void prefix_patches(struct patch *p)
3775
static int apply_patch(int fd, const char *filename, int options)
3776
{
3777
size_t offset;
3729
- struct strbuf buf = STRBUF_INIT;
3778
+ struct strbuf buf = STRBUF_INIT; /* owns the patch text */
3779
struct patch *list = NULL, **listp = &list;
3780
int skipped_patch = 0;
3781