Merge branch 'js/range-diff-one-side-only'

[thirdparty/git.git] / merge-ort.h

diff --git a/merge-ort.h b/merge-ort.h
index 74adccad162b655e2174354eab093217dbd5b124..d53a0a339f338c4fcc0b3965e69319741bd546bf 100644 (file)
--- a/merge-ort.h
+++ b/merge-ort.h
@@ -7,7 +7,14 @@ struct commit;
 struct tree;
 
 struct merge_result {
-       /* Whether the merge is clean */
+       /*
+        * Whether the merge is clean; possible values:
+        *    1: clean
+        *    0: not clean (merge conflicts)
+        *   <0: operation aborted prematurely.  (object database
+        *       unreadable, disk full, etc.)  Worktree may be left in an
+        *       inconsistent state if operation failed near the end.
+        */
        int clean;
 
        /*
@@ -27,6 +34,16 @@ struct merge_result {
 /*
  * rename-detecting three-way merge with recursive ancestor consolidation.
  * working tree and index are untouched.
+ *
+ * merge_bases will be consumed (emptied) so make a copy if you need it.
+ *
+ * NOTE: empirically, the recursive algorithm will perform better if you
+ *       pass the merge_bases in the order of oldest commit to the
+ *       newest[1][2].
+ *
+ *       [1] https://lore.kernel.org/git/nycvar.QRO.7.76.6.1907252055500.21907@tvgsbejvaqbjf.bet/
+ *       [2] commit 8918b0c9c2 ("merge-recur: try to merge older merge bases
+ *           first", 2006-08-09)
  */
 void merge_incore_recursive(struct merge_options *opt,
                            struct commit_list *merge_bases,