Commit 5e44d9bcb6d5b20922f49b1913723186f8ced8b5
2015-01-05T11:34:17
Better document `git_merge_commits` `git_merge_commits` (and thus `git_merge`) do not use the same strategy as `git-merge-recursive` wherein they can produce an artificial common ancestor that is the merge of all common ancestors. Document this accordingly.
diff --git a/include/git2/merge.h b/include/git2/merge.h
index 09900f1..40330d0 100644
--- a/include/git2/merge.h
+++ b/include/git2/merge.h
@@ -479,6 +479,10 @@ GIT_EXTERN(int) git_merge_trees(
* or checked out. If the index is to be converted to a tree, the caller
* should resolve any conflicts that arose as part of the merge.
*
+ * The merge performed uses the first common ancestor, unlike the
+ * `git-merge-recursive` strategy, which may produce an artificial common
+ * ancestor tree when there are multiple ancestors.
+ *
* The returned index must be freed explicitly with `git_index_free`.
*
* @param out pointer to store the index result in
@@ -501,6 +505,10 @@ GIT_EXTERN(int) git_merge_commits(
* to the index. Callers should inspect the repository's index after this
* completes, resolve any conflicts and prepare a commit.
*
+ * The merge performed uses the first common ancestor, unlike the
+ * `git-merge-recursive` strategy, which may produce an artificial common
+ * ancestor tree when there are multiple ancestors.
+ *
* For compatibility with git, the repository is put into a merging
* state. Once the commit is done (or if the uses wishes to abort),
* you should clear this state by calling