Merge pull request #2799 from ethomson/merge_doc

Better document `git_merge_commits`

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