line-log: reorganize and document line-log.c

With the range-set algebra extracted, line-log.c is the "git log -L"
machinery proper, but its structure was still hard to see.

Group the remaining code by concern behind short section banners (the
per-path line_log_data list; parsing -L arguments; computing a commit's
diff; and the history walk), moving collect_diff() and the line_log_data
helpers next to the code they belong with.

Add a file header describing the two traversal modes (eager parent
rewriting via line_log_filter(), versus the lazy per-commit walk driven
from get_commit_action()), and a comment on the per-commit entry point
describing how it dispatches on a commit's shape.

Rename line_log_process_ranges_arbitrary_commit() to the shorter
line_log_process_commit(): it processes one commit, and "arbitrary" was
more puzzling than descriptive.

While here, drop two bits of dead code the motion made obvious: a
redundant trailing "return;" at the end of fill_blob_sha1(), and a
commented-out debug fprintf in diff_might_be_rename().

No functional change intended.

Signed-off-by: Michael Montalbo <mmontalbo@gmail.com>

Author: mmontalbo

line-log.c

@@ -20,6 +20,31 @@
 #include "bloom.h"
 #include "tree-walk.h"
 
+/*
+ * "git log -L": follow a set of line ranges through history.
+ *
+ * Each interesting commit carries a "struct line_log_data" (a per-path
+ * list of tracked "struct range_set" line ranges) as a decoration in
+ * rev->line_log_data.  Walking from a commit to its parent maps those
+ * ranges back across the commit's diff (process_ranges_ordinary_commit()
+ * via range_set_map_across_diff()), so each parent inherits the ranges
+ * it is responsible for.
+ *
+ * The walk runs in one of two modes:
+ *
+ *   - Eager, under parent rewriting (want_ancestry(), e.g. --graph):
+ *     line_log_filter() processes every commit in prepare_revision_walk()
+ *     and rewrites the parent links.
+ *
+ *   - Lazy, for a plain "git log -L": each commit is processed on demand
+ *     during the walk, from get_commit_action() in revision.c.
+ *
+ * Both share line_log_process_commit(), which processes
+ * one commit and reports whether it changed a tracked range.
+ */
+
+/* line_log_data: the sorted per-path list of tracked line ranges. */
+
 static void line_log_data_init(struct line_log_data *r)
 {
 	memset(r, 0, sizeof(struct line_log_data));
@@ -92,42 +117,119 @@ static void line_log_data_insert(struct line_log_data **list,
 	}
 }
 
-struct collect_diff_cbdata {
-	struct diff_ranges *diff;
-};
+static struct line_log_data *line_log_data_copy_one(struct line_log_data *r)
+{
+	struct line_log_data *ret = xmalloc(sizeof(*ret));
 
-static int collect_diff_cb(long start_a, long count_a,
-			   long start_b, long count_b,
-			   void *data)
+	assert(r);
+	line_log_data_init(ret);
+	range_set_copy(&ret->ranges, &r->ranges);
+
+	ret->path = xstrdup(r->path);
+
+	return ret;
+}
+
+static struct line_log_data *
+line_log_data_copy(struct line_log_data *r)
 {
-	struct collect_diff_cbdata *d = data;
+	struct line_log_data *ret = NULL;
+	struct line_log_data *tmp = NULL, *prev = NULL;
 
-	if (count_a >= 0)
-		range_set_append(&d->diff->parent, start_a, start_a + count_a);
-	if (count_b >= 0)
-		range_set_append(&d->diff->target, start_b, start_b + count_b);
+	assert(r);
+	ret = tmp = prev = line_log_data_copy_one(r);
+	r = r->next;
+	while (r) {
+		tmp = line_log_data_copy_one(r);
+		prev->next = tmp;
+		prev = tmp;
+		r = r->next;
+	}
 
-	return 0;
+	return ret;
 }
 
-static int collect_diff(mmfile_t *parent, mmfile_t *target, struct diff_ranges *out)
+/* merge two range sets across files */
+static struct line_log_data *line_log_data_merge(struct line_log_data *a,
+						 struct line_log_data *b)
 {
-	struct collect_diff_cbdata cbdata = {NULL};
-	xpparam_t xpp;
-	xdemitconf_t xecfg;
-	xdemitcb_t ecb;
+	struct line_log_data *head = NULL, **pp = &head;
 
-	memset(&xpp, 0, sizeof(xpp));
-	memset(&xecfg, 0, sizeof(xecfg));
-	xecfg.ctxlen = xecfg.interhunkctxlen = 0;
+	while (a || b) {
+		struct line_log_data *src;
+		struct line_log_data *src2 = NULL;
+		struct line_log_data *d;
+		int cmp;
+		if (!a)
+			cmp = 1;
+		else if (!b)
+			cmp = -1;
+		else
+			cmp = strcmp(a->path, b->path);
+		if (cmp < 0) {
+			src = a;
+			a = a->next;
+		} else if (cmp == 0) {
+			src = a;
+			a = a->next;
+			src2 = b;
+			b = b->next;
+		} else {
+			src = b;
+			b = b->next;
+		}
+		d = xmalloc(sizeof(struct line_log_data));
+		line_log_data_init(d);
+		d->path = xstrdup(src->path);
+		*pp = d;
+		pp = &d->next;
+		if (src2)
+			range_set_union(&d->ranges, &src->ranges, &src2->ranges);
+		else
+			range_set_copy(&d->ranges, &src->ranges);
+	}
 
-	cbdata.diff = out;
-	xecfg.hunk_func = collect_diff_cb;
-	memset(&ecb, 0, sizeof(ecb));
-	ecb.priv = &cbdata;
-	return xdi_diff(parent, target, &xpp, &xecfg, &ecb);
+	return head;
+}
+
+static void add_line_range(struct rev_info *revs, struct commit *commit,
+			   struct line_log_data *range)
+{
+	struct line_log_data *old_line = NULL;
+	struct line_log_data *new_line = NULL;
+
+	old_line = lookup_decoration(&revs->line_log_data, &commit->object);
+	if (old_line && range) {
+		new_line = line_log_data_merge(old_line, range);
+		free_line_log_data(old_line);
+	} else if (range)
+		new_line = line_log_data_copy(range);
+
+	if (new_line)
+		add_decoration(&revs->line_log_data, &commit->object, new_line);
+}
+
+static void clear_commit_line_range(struct rev_info *revs, struct commit *commit)
+{
+	struct line_log_data *r;
+	r = lookup_decoration(&revs->line_log_data, &commit->object);
+	if (!r)
+		return;
+	free_line_log_data(r);
+	add_decoration(&revs->line_log_data, &commit->object, NULL);
 }
 
+static struct line_log_data *lookup_line_range(struct rev_info *revs,
+					       struct commit *commit)
+{
+	return lookup_decoration(&revs->line_log_data, &commit->object);
+}
+
+/*
+ * Parsing "-L" arguments into an initial set of tracked ranges and the
+ * pathspec that limits the diff.  line_log_init() is the entry point.
+ */
+
 static struct commit *check_single_commit(struct rev_info *revs)
 {
 	struct object *commit = NULL;
@@ -164,8 +266,6 @@ static void fill_blob_sha1(struct repository *r, struct commit *commit,
 	if (get_tree_entry(r, &commit->object.oid, spec->path, &oid, &mode))
 		die("There is no path %s in the commit", spec->path);
 	fill_filespec(spec, &oid, 1, mode);
-
-	return;
 }
 
 static void fill_line_ends(struct repository *r,
@@ -282,114 +382,6 @@ parse_lines(struct repository *r, struct commit *commit,
 	return ranges;
 }
 
-static struct line_log_data *line_log_data_copy_one(struct line_log_data *r)
-{
-	struct line_log_data *ret = xmalloc(sizeof(*ret));
-
-	assert(r);
-	line_log_data_init(ret);
-	range_set_copy(&ret->ranges, &r->ranges);
-
-	ret->path = xstrdup(r->path);
-
-	return ret;
-}
-
-static struct line_log_data *
-line_log_data_copy(struct line_log_data *r)
-{
-	struct line_log_data *ret = NULL;
-	struct line_log_data *tmp = NULL, *prev = NULL;
-
-	assert(r);
-	ret = tmp = prev = line_log_data_copy_one(r);
-	r = r->next;
-	while (r) {
-		tmp = line_log_data_copy_one(r);
-		prev->next = tmp;
-		prev = tmp;
-		r = r->next;
-	}
-
-	return ret;
-}
-
-/* merge two range sets across files */
-static struct line_log_data *line_log_data_merge(struct line_log_data *a,
-						 struct line_log_data *b)
-{
-	struct line_log_data *head = NULL, **pp = &head;
-
-	while (a || b) {
-		struct line_log_data *src;
-		struct line_log_data *src2 = NULL;
-		struct line_log_data *d;
-		int cmp;
-		if (!a)
-			cmp = 1;
-		else if (!b)
-			cmp = -1;
-		else
-			cmp = strcmp(a->path, b->path);
-		if (cmp < 0) {
-			src = a;
-			a = a->next;
-		} else if (cmp == 0) {
-			src = a;
-			a = a->next;
-			src2 = b;
-			b = b->next;
-		} else {
-			src = b;
-			b = b->next;
-		}
-		d = xmalloc(sizeof(struct line_log_data));
-		line_log_data_init(d);
-		d->path = xstrdup(src->path);
-		*pp = d;
-		pp = &d->next;
-		if (src2)
-			range_set_union(&d->ranges, &src->ranges, &src2->ranges);
-		else
-			range_set_copy(&d->ranges, &src->ranges);
-	}
-
-	return head;
-}
-
-static void add_line_range(struct rev_info *revs, struct commit *commit,
-			   struct line_log_data *range)
-{
-	struct line_log_data *old_line = NULL;
-	struct line_log_data *new_line = NULL;
-
-	old_line = lookup_decoration(&revs->line_log_data, &commit->object);
-	if (old_line && range) {
-		new_line = line_log_data_merge(old_line, range);
-		free_line_log_data(old_line);
-	} else if (range)
-		new_line = line_log_data_copy(range);
-
-	if (new_line)
-		add_decoration(&revs->line_log_data, &commit->object, new_line);
-}
-
-static void clear_commit_line_range(struct rev_info *revs, struct commit *commit)
-{
-	struct line_log_data *r;
-	r = lookup_decoration(&revs->line_log_data, &commit->object);
-	if (!r)
-		return;
-	free_line_log_data(r);
-	add_decoration(&revs->line_log_data, &commit->object, NULL);
-}
-
-static struct line_log_data *lookup_line_range(struct rev_info *revs,
-					       struct commit *commit)
-{
-	return lookup_decoration(&revs->line_log_data, &commit->object);
-}
-
 static int same_paths_in_pathspec_and_range(struct pathspec *pathspec,
 					    struct line_log_data *range)
 {
@@ -434,6 +426,47 @@ void line_log_init(struct rev_info *rev, const char *prefix, struct string_list
 	free_line_log_data(range);
 }
 
+/*
+ * Compute one commit's diff against a parent as a set of changed line
+ * ranges (collect_diff), then walk the tracked ranges back across it.
+ */
+
+struct collect_diff_cbdata {
+	struct diff_ranges *diff;
+};
+
+static int collect_diff_cb(long start_a, long count_a,
+			   long start_b, long count_b,
+			   void *data)
+{
+	struct collect_diff_cbdata *d = data;
+
+	if (count_a >= 0)
+		range_set_append(&d->diff->parent, start_a, start_a + count_a);
+	if (count_b >= 0)
+		range_set_append(&d->diff->target, start_b, start_b + count_b);
+
+	return 0;
+}
+
+static int collect_diff(mmfile_t *parent, mmfile_t *target, struct diff_ranges *out)
+{
+	struct collect_diff_cbdata cbdata = {NULL};
+	xpparam_t xpp;
+	xdemitconf_t xecfg;
+	xdemitcb_t ecb;
+
+	memset(&xpp, 0, sizeof(xpp));
+	memset(&xecfg, 0, sizeof(xecfg));
+	xecfg.ctxlen = xecfg.interhunkctxlen = 0;
+
+	cbdata.diff = out;
+	xecfg.hunk_func = collect_diff_cb;
+	memset(&ecb, 0, sizeof(ecb));
+	ecb.priv = &cbdata;
+	return xdi_diff(parent, target, &xpp, &xecfg, &ecb);
+}
+
 static void move_diff_queue(struct diff_queue_struct *dst,
 			    struct diff_queue_struct *src)
 {
@@ -475,11 +508,8 @@ static inline int diff_might_be_rename(void)
 {
 	int i;
 	for (i = 0; i < diff_queued_diff.nr; i++)
-		if (!DIFF_FILE_VALID(diff_queued_diff.queue[i]->one)) {
-			/* fprintf(stderr, "diff_might_be_rename found creation of: %s\n", */
-			/* 	diff_queued_diff.queue[i]->two->path); */
+		if (!DIFF_FILE_VALID(diff_queued_diff.queue[i]->one))
 			return 1;
-		}
 	return 0;
 }
 
@@ -695,6 +725,8 @@ static int bloom_filter_check(struct rev_info *rev,
 	return result;
 }
 
+/* Walking history: map each commit's tracked ranges to its parent(s). */
+
 static int process_ranges_ordinary_commit(struct rev_info *rev, struct commit *commit,
 					  struct line_log_data *range)
 {
@@ -780,7 +812,15 @@ static int process_ranges_merge_commit(struct rev_info *rev, struct commit *comm
 	/* NEEDSWORK evil merge detection stuff */
 }
 
-int line_log_process_ranges_arbitrary_commit(struct rev_info *rev, struct commit *commit)
+/*
+ * Entry point for one commit (both traversal modes call this).  Dispatch
+ * on the commit's shape: no tracked ranges (nothing to do); a Bloom
+ * filter proving the file untouched (carry ranges to the sole parent
+ * without diffing); a merge (map across each parent, splitting the
+ * ranges); or an ordinary commit.  A commit that changed no tracked
+ * range is marked TREESAME so the caller can prune it.
+ */
+int line_log_process_commit(struct rev_info *rev, struct commit *commit)
 {
 	struct line_log_data *range = lookup_line_range(rev, commit);
 	int changed = 0;
@@ -828,7 +868,7 @@ int line_log_filter(struct rev_info *rev)
 	while (list) {
 		struct commit_list *to_free = NULL;
 		commit = list->item;
-		if (line_log_process_ranges_arbitrary_commit(rev, commit)) {
+		if (line_log_process_commit(rev, commit)) {
 			*pp = list;
 			pp = &list->next;
 		} else