From 5e44d9bcb6d5b20922f49b1913723186f8ced8b5 Mon Sep 17 00:00:00 2001 From: Edward Thomson Date: Mon, 5 Jan 2015 11:34:17 -0600 Subject: [PATCH] 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. --- include/git2/merge.h | 8 ++++++++ 1 file changed, 8 insertions(+) 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