rerere: explain "rerere forget" codepath

Explain the internals of rerere as in-code comments, while
sprinkling "NEEDSWORK" comment to highlight iffy bits and
questionable assumptions.

This covers the codepath that implements "rerere forget".

Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/rerere.c b/rerere.c
index 6961c1738745cb840dd66833e230b845b7bb5184..c3e34d10d9bacff099fa7c3fadada324eff0314b 100644 (file)
--- a/rerere.c
+++ b/rerere.c
@@ -422,6 +422,10 @@ static int handle_cache(const char *path, unsigned char *sha1, const char *outpu
        strbuf_init(&io.input, 0);
        strbuf_attach(&io.input, result.ptr, result.size, result.size);
 
        strbuf_init(&io.input, 0);
        strbuf_attach(&io.input, result.ptr, result.size, result.size);
 

+       /*
+        * Grab the conflict ID and optionally write the original
+        * contents with conflict markers out.
+        */

        hunk_no = handle_path(sha1, (struct rerere_io *)&io, marker_size);
        strbuf_release(&io.input);
        if (io.io.output)
        hunk_no = handle_path(sha1, (struct rerere_io *)&io, marker_size);
        strbuf_release(&io.input);
        if (io.io.output)


@@ -786,9 +790,15 @@ static int rerere_forget_one_path(const char *path, struct string_list *rr)
        int ret;
        struct string_list_item *item;
 
        int ret;
        struct string_list_item *item;
 

+       /*
+        * Recreate the original conflict from the stages in the
+        * index and compute the conflict ID
+        */

        ret = handle_cache(path, sha1, NULL);
        if (ret < 1)
                return error("Could not parse conflict hunks in '%s'", path);
        ret = handle_cache(path, sha1, NULL);
        if (ret < 1)
                return error("Could not parse conflict hunks in '%s'", path);

+
+       /* Nuke the recorded resolution for the conflict */

        hex = xstrdup(sha1_to_hex(sha1));
        filename = rerere_path(hex, "postimage");
        if (unlink(filename))
        hex = xstrdup(sha1_to_hex(sha1));
        filename = rerere_path(hex, "postimage");
        if (unlink(filename))


@@ -796,9 +806,18 @@ static int rerere_forget_one_path(const char *path, struct string_list *rr)
                        ? error("no remembered resolution for %s", path)
                        : error("cannot unlink %s: %s", filename, strerror(errno)));
 
                        ? error("no remembered resolution for %s", path)
                        : error("cannot unlink %s: %s", filename, strerror(errno)));
 

+       /*
+        * Update the preimage so that the user can resolve the
+        * conflict in the working tree, run us again to record
+        * the postimage.
+        */

        handle_cache(path, sha1, rerere_path(hex, "preimage"));
        fprintf(stderr, "Updated preimage for '%s'\n", path);
 
        handle_cache(path, sha1, rerere_path(hex, "preimage"));
        fprintf(stderr, "Updated preimage for '%s'\n", path);
 

+       /*
+        * And remember that we can record resolution for this
+        * conflict when the user is done.
+        */

        item = string_list_insert(rr, path);
        free(item->util);
        item->util = hex;
        item = string_list_insert(rr, path);
        free(item->util);
        item->util = hex;


@@ -817,6 +836,11 @@ int rerere_forget(struct pathspec *pathspec)
 
        fd = setup_rerere(&merge_rr, RERERE_NOAUTOUPDATE);
 
 
        fd = setup_rerere(&merge_rr, RERERE_NOAUTOUPDATE);
 

+       /*
+        * The paths may have been resolved (incorrectly);
+        * recover the original conflicted state and then
+        * find the conflicted paths.
+        */

        unmerge_cache(pathspec);
        find_conflict(&conflict);
        for (i = 0; i < conflict.nr; i++) {
        unmerge_cache(pathspec);
        find_conflict(&conflict);
        for (i = 0; i < conflict.nr; i++) {