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.

1 files changed, 8 insertions, 0 deletions

diff --git a/include/git2/merge.h b/include/git2/merge.h
index 09900f12b..40330d0d8 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