rerere: explain the primary codepath
Explain the internals of rerere as in-code comments, while sprinkling "NEEDSWORK" comment to highlight iffy bits and questionable assumptions. This one covers the codepath reached from rerere(), the primary interface to the subsystem. Signed-off-by: Junio C Hamano <gitster@pobox.com>
Junio C Hamano committed
Jun 30, 2015 at 22:40 UTC
cc899eca552a9b93788e6bca34aa0e4d86b251a0
1 file changed
+82
-13
rerere.c
+82
-13
@@ -206,6 +206,21 @@ static int is_cmarker(char *buf, int marker_char, int marker_size)
206
return isspace(*buf);
207
}
208
209
+/*
210
+ * Read contents a file with conflicts, normalize the conflicts
211
+ * by (1) discarding the common ancestor version in diff3-style,
212
+ * (2) reordering our side and their side so that whichever sorts
213
+ * alphabetically earlier comes before the other one, while
214
+ * computing the "conflict ID", which is just an SHA-1 hash of
215
+ * one side of the conflict, NUL, the other side of the conflict,
216
+ * and NUL concatenated together.
217
+ *
218
+ * Return the number of conflict hunks found.
219
+ *
220
+ * NEEDSWORK: the logic and theory of operation behind this conflict
221
+ * normalization may deserve to be documented somewhere, perhaps in
222
+ * Documentation/technical/rerere.txt.
223
+ */
224
static int handle_path(unsigned char *sha1, struct rerere_io *io, int marker_size)
225
{
226
git_SHA_CTX ctx;
@@ -276,6 +291,10 @@ static int handle_path(unsigned char *sha1, struct rerere_io *io, int marker_siz
291
return hunk_no;
292
}
293
294
+/*
295
+ * Scan the path for conflicts, do the "handle_path()" thing above, and
296
+ * return the number of conflict hunks found.
297
+ */
298
static int handle_file(const char *path, unsigned char *sha1, const char *output)
299
{
300
int hunk_no = 0;
@@ -515,29 +534,54 @@ int rerere_remaining(struct string_list *merge_rr)
534
return 0;
535
}
536
537
+/*
538
+ * Find the conflict identified by "name"; the change between its
539
+ * "preimage" (i.e. a previous contents with conflict markers) and its
540
+ * "postimage" (i.e. the corresponding contents with conflicts
541
+ * resolved) may apply cleanly to the contents stored in "path", i.e.
542
+ * the conflict this time around.
543
+ *
544
+ * Returns 0 for successful replay of recorded resolution, or non-zero
545
+ * for failure.
546
+ */
547
static int merge(const char *name, const char *path)
548
{
549
int ret;
550
mmfile_t cur = {NULL, 0}, base = {NULL, 0}, other = {NULL, 0};
551
mmbuffer_t result = {NULL, 0};
552
553
+ /*
554
+ * Normalize the conflicts in path and write it out to
555
+ * "thisimage" temporary file.
556
+ */
557
if (handle_file(path, NULL, rerere_path(name, "thisimage")) < 0)
558
return 1;
559
560
if (read_mmfile(&cur, rerere_path(name, "thisimage")) ||
528
- read_mmfile(&base, rerere_path(name, "preimage")) ||
529
- read_mmfile(&other, rerere_path(name, "postimage"))) {
561
+ read_mmfile(&base, rerere_path(name, "preimage")) ||
562
+ read_mmfile(&other, rerere_path(name, "postimage"))) {
563
ret = 1;
564
goto out;
565
}
566
+
567
+ /*
568
+ * A three-way merge. Note that this honors user-customizable
569
+ * low-level merge driver settings.
570
+ */
571
ret = ll_merge(&result, path, &base, NULL, &cur, "", &other, "", NULL);
572
if (!ret) {
573
FILE *f;
574
575
+ /*
576
+ * A successful replay of recorded resolution.
577
+ * Mark that "postimage" was used to help gc.
578
+ */
579
if (utime(rerere_path(name, "postimage"), NULL) < 0)
580
warning("failed utime() on %s: %s",
581
rerere_path(name, "postimage"),
582
strerror(errno));
583
+
584
+ /* Update "path" with the resolution */
585
f = fopen(path, "w");
586
if (!f)
587
return error("Could not open %s: %s", path,
@@ -590,41 +634,61 @@ static int do_plain_rerere(struct string_list *rr, int fd)
634
find_conflict(&conflict);
635
636
/*
593
- * MERGE_RR records paths with conflicts immediately after merge
594
- * failed. Some of the conflicted paths might have been hand resolved
595
- * in the working tree since then, but the initial run would catch all
596
- * and register their preimages.
637
+ * MERGE_RR records paths with conflicts immediately after
638
+ * merge failed. Some of the conflicted paths might have been
639
+ * hand resolved in the working tree since then, but the
640
+ * initial run would catch all and register their preimages.
641
*/
598
-
642
for (i = 0; i < conflict.nr; i++) {
643
const char *path = conflict.items[i].string;
644
if (!string_list_has_string(rr, path)) {
645
unsigned char sha1[20];
646
char *hex;
647
int ret;
648
+
649
+ /*
650
+ * Ask handle_file() to scan and assign a
651
+ * conflict ID. No need to write anything out
652
+ * yet.
653
+ */
654
ret = handle_file(path, sha1, NULL);
655
if (ret < 1)
656
continue;
657
hex = xstrdup(sha1_to_hex(sha1));
658
string_list_insert(rr, path)->util = hex;
659
+
660
+ /*
661
+ * If the directory does not exist, create
662
+ * it. mkdir_in_gitdir() will fail with
663
+ * EEXIST if there already is one.
664
+ *
665
+ * NEEDSWORK: make sure "gc" does not remove
666
+ * preimage without removing the directory.
667
+ */
668
if (mkdir_in_gitdir(git_path("rr-cache/%s", hex)))
669
continue;
670
+
671
+ /*
672
+ * We are the first to encounter this
673
+ * conflict. Ask handle_file() to write the
674
+ * normalized contents to the "preimage" file.
675
+ */
676
handle_file(path, NULL, rerere_path(hex, "preimage"));
677
fprintf(stderr, "Recorded preimage for '%s'\n", path);
678
}
679
}
680
681
/*
618
- * Now some of the paths that had conflicts earlier might have been
619
- * hand resolved. Others may be similar to a conflict already that
620
- * was resolved before.
682
+ * Some of the paths that had conflicts earlier might have
683
+ * been resolved by the user. Others may be similar to a
684
+ * conflict already that was resolved before.
685
*/
622
-
686
for (i = 0; i < rr->nr; i++) {
687
int ret;
688
const char *path = rr->items[i].string;
689
const char *name = (const char *)rr->items[i].util;
690
691
+ /* Is there a recorded resolution we could attempt to apply? */
692
if (has_rerere_resolution(name)) {
693
if (merge(name, path))
694
continue;
@@ -638,13 +702,13 @@ static int do_plain_rerere(struct string_list *rr, int fd)
702
goto mark_resolved;
703
}
704
641
- /* Let's see if we have resolved it. */
705
+ /* Let's see if the user has resolved it. */
706
ret = handle_file(path, NULL, NULL);
707
if (ret)
708
continue;
709
646
- fprintf(stderr, "Recorded resolution for '%s'.\n", path);
710
copy_file(rerere_path(name, "postimage"), path, 0666);
711
+ fprintf(stderr, "Recorded resolution for '%s'.\n", path);
712
mark_resolved:
713
free(rr->items[i].util);
714
rr->items[i].util = NULL;
@@ -698,6 +762,11 @@ int setup_rerere(struct string_list *merge_rr, int flags)
762
return fd;
763
}
764
765
+/*
766
+ * The main entry point that is called internally from codepaths that
767
+ * perform mergy operations, possibly leaving conflicted index entries
768
+ * and working tree files.
769
+ */
770
int rerere(int flags)
771
{
772
struct string_list merge_rr = STRING_LIST_INIT_DUP;