path: root/merge-recursive.h
diff options
authorElijah Newren <>2019-08-17 18:41:30 (GMT)
committerJunio C Hamano <>2019-08-19 17:08:03 (GMT)
commitb4db8a2b768742f4f43d4a6cdb1db39c2ffc9f7f (patch)
treeed09adf5db7d6e254b5fb76172426f33336b0b15 /merge-recursive.h
parent98a1d3d88895a1cbc01b88627776bb4e2bfd6b84 (diff)
merge-recursive: remove useless parameter in merge_trees()
merge_trees() took a results parameter that would only be written when opt->call_depth was positive, which is never the case now that merge_trees_internal() has been split from merge_trees(). Remove the misleading and unused parameter from merge_trees(). While at it, add some comments explaining how the output of merge_trees() and merge_recursive() differ. Signed-off-by: Elijah Newren <> Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'merge-recursive.h')
1 files changed, 16 insertions, 4 deletions
diff --git a/merge-recursive.h b/merge-recursive.h
index f1b6ef3..18012ff 100644
--- a/merge-recursive.h
+++ b/merge-recursive.h
@@ -74,19 +74,31 @@ static inline int merge_detect_rename(struct merge_options *o)
o->diff_detect_rename >= 0 ? o->diff_detect_rename : 1;
-/* merge_trees() but with recursive ancestor consolidation */
+ * merge_recursive is like merge_trees() but with recursive ancestor
+ * consolidation, and when successful, it creates an actual commit
+ * and writes its address to *result.
+ *
+ * NOTE: empirically, about a decade ago it was determined that with more
+ * than two merge bases, optimal behavior was found when the
+ * ancestors were passed in the order of oldest merge base to newest
+ * one. Also, ancestors will be consumed (emptied) so make a copy if
+ * you need it.
+ */
int merge_recursive(struct merge_options *o,
struct commit *h1,
struct commit *h2,
struct commit_list *ancestors,
struct commit **result);
-/* rename-detecting three-way merge, no recursion */
+ * rename-detecting three-way merge, no recursion; result of merge is written
+ * to opt->repo->index.
+ */
int merge_trees(struct merge_options *o,
struct tree *head,
struct tree *merge,
- struct tree *common,
- struct tree **result);
+ struct tree *common);
* "git-merge-recursive" can be fed trees; wrap them into