[PATCH 1/3] bisect: fix memory leak and document `find_bisection()`

["Martin Ågren" <martin.agren@gmail.com>]

`find_bisection()` rebuilds the commit list it is given by reversing it
and skipping uninteresting commits. The uninteresting list entries are
leaked. Free them to fix the leak.

While we're here and understand what's going on, document the function.
In particular, make sure to document that the original list should not
be examined by the caller.

Signed-off-by: Martin Ågren <martin.agren@gmail.com>
---
 bisect.c | 4 +++-
 bisect.h | 7 +++++++
 2 files changed, 10 insertions(+), 1 deletion(-)

diff --git a/bisect.c b/bisect.c
index 96beeb5d1..f9de4f2e8 100644
--- a/bisect.c
+++ b/bisect.c
@@ -380,8 +380,10 @@ struct commit_list *find_bisection(struct commit_list *list,
 		unsigned flags = p->item->object.flags;
 
 		next = p->next;
-		if (flags & UNINTERESTING)
+		if (flags & UNINTERESTING) {
+			free(p);
 			continue;
+		}
 		p->next = last;
 		last = p;
 		if (!(flags & TREESAME))
diff --git a/bisect.h b/bisect.h
index acd12ef80..cf135f16e 100644
--- a/bisect.h
+++ b/bisect.h
@@ -1,6 +1,13 @@
 #ifndef BISECT_H
 #define BISECT_H
 
+/*
+ * Find bisection. If something is found, `reaches` will be the number of
+ * commits that the best commit reaches. `all` will be the count of
+ * non-SAMETREE commits. If `find_all` is set, all non-SAMETREE commits are
+ * returned sorted, otherwise only a single best commit is returned. The
+ * original list will be left in an undefined state and should not be examined.
+ */
 extern struct commit_list *find_bisection(struct commit_list *list,
 					  int *reaches, int *all,
 					  int find_all);
-- 
2.15.0.415.gac1375d7e