Doc merge_analysis and some enums (#23435)

* Doc merge_analysis and some enums

base/libgit2/consts.jl

@@ -190,11 +190,29 @@ module Consts
                                 MERGE_FILE_FAVOR_OURS   = 1,
                                 MERGE_FILE_FAVOR_THEIRS = 2,
                                 MERGE_FILE_FAVOR_UNION  = 3)
-
+    """ The user's instructions for how to perform a possible merge.
+    * `MERGE_PREFERENCE_NONE`: the user has no preference.
+    * `MERGE_PREFERENCE_NO_FASTFORWARD`: do not allow any fast-forward merges.
+    * `MERGE_PREFERENCE_FASTFORWARD_ONLY`: allow only fast-forward merges and no
+      other type (which may introduce conflicts).
+    """
     @enum(GIT_MERGE_PREFERENCE, MERGE_PREFERENCE_NONE             = 0,
                                 MERGE_PREFERENCE_NO_FASTFORWARD   = 1,
                                 MERGE_PREFERENCE_FASTFORWARD_ONLY = 2)
-
+    """ Result of analysis on merge possibilities.
+    * `MERGE_ANALYSIS_NONE`: it is not possible to merge the elements of the input commits.
+    * `MERGE_ANALYSIS_NORMAL`: a regular merge, when HEAD and the commits that the
+      user wishes to merge have all diverged from a common ancestor. In this case the
+      changes have to be resolved and conflicts may occur.
+    * `MERGE_ANALYSIS_UP_TO_DATE`: all the input commits the user wishes to merge can
+      be reached from HEAD, so no merge needs to be performed.
+    * `MERGE_ANALYSIS_FASTFORWARD`: the input commit is a descendant of HEAD and so no
+      merge needs to be performed - instead, the user can simply checkout the
+      input commit(s).
+    * `MERGE_ANALYSIS_UNBORN`: the HEAD of the repository refers to a commit which does not
+      exist. It is not possible to merge, but it may be possible to checkout the input
+      commits.
+    """
     @enum(GIT_MERGE_ANALYSIS, MERGE_ANALYSIS_NONE        = 0,
                               MERGE_ANALYSIS_NORMAL      = 1 << 0,
                               MERGE_ANALYSIS_UP_TO_DATE  = 1 << 1,

base/libgit2/merge.jl

@@ -47,6 +47,34 @@ function GitHash(ann::GitAnnotated)
     unsafe_load(ccall((:git_annotated_commit_id, :libgit2), Ptr{GitHash}, (Ptr{Void},), ann.ptr))
 end
 
+"""
+    merge_analysis(repo::GitRepo, anns::Vector{GitAnnotated}) -> analysis, preference
+
+Run analysis on the branches pointed to by the annotated branch tips `anns` and
+determine under what circumstances they can be merged. For instance, if `anns[1]`
+is simply an ancestor of `ann[2]`, then `merge_analysis` will report that a
+fast-forward merge is possible.
+
+`merge_analysis` returns two outputs. `analysis` has several possible values:
+    * `MERGE_ANALYSIS_NONE`: it is not possible to merge the elements of `anns`.
+    * `MERGE_ANALYSIS_NORMAL`: a regular merge, when HEAD and the commits that the
+      user wishes to merge have all diverged from a common ancestor. In this case the
+      changes have to be resolved and conflicts may occur.
+    * `MERGE_ANALYSIS_UP_TO_DATE`: all the input commits the user wishes to merge can
+      be reached from HEAD, so no merge needs to be performed.
+    * `MERGE_ANALYSIS_FASTFORWARD`: the input commit is a descendant of HEAD and so no
+      merge needs to be performed - instead, the user can simply checkout the
+      input commit(s).
+    * `MERGE_ANALYSIS_UNBORN`: the HEAD of the repository refers to a commit which does not
+      exist. It is not possible to merge, but it may be possible to checkout the input
+      commits.
+`preference` also has several possible values:
+    * `MERGE_PREFERENCE_NONE`: the user has no preference.
+    * `MERGE_PREFERENCE_NO_FASTFORWARD`: do not allow any fast-forward merges.
+    * `MERGE_PREFERENCE_FASTFORWARD_ONLY`: allow only fast-forward merges and no
+      other type (which may introduce conflicts).
+`preference` can be controlled through the repository or global git configuration.
+"""
 function merge_analysis(repo::GitRepo, anns::Vector{GitAnnotated})
     analysis = Ref{Cint}(0)
     preference = Ref{Cint}(0)
@@ -61,7 +89,9 @@ end
 """
     ffmerge!(repo::GitRepo, ann::GitAnnotated)
 
-Fastforward merge changes into current head
+Fastforward merge changes into current HEAD. This is only possible if the commit
+referred to by `ann` is descended from the current HEAD (e.g. if pulling changes
+from a remote branch which is simply ahead of the local branch tip).
 """
 function ffmerge!(repo::GitRepo, ann::GitAnnotated)
     cmt = GitCommit(repo, GitHash(ann))

doc/src/devdocs/libgit2.md

@@ -102,6 +102,7 @@ Base.LibGit2.map(::Function, ::Base.LibGit2.GitRevWalker; ::Base.LibGit2.GitHash
 Base.LibGit2.mirror_callback
 Base.LibGit2.mirror_cb
 Base.LibGit2.message
+Base.LibGit2.merge_analysis
 Base.LibGit2.name
 Base.LibGit2.need_update
 Base.LibGit2.objtype