Doc merge_analysis and some enums

base/libgit2/consts.jl

@@ -160,11 +160,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 `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.
+ """
  @enum(GIT_MERGE_ANALYSIS, MERGE_ANALYSIS_NONE = 0,
  MERGE_ANALYSIS_NORMAL = 1 << 0,
  MERGE_ANALYSIS_UP_TO_DATE = 1 << 1,

base/libgit2/merge.jl

@@ -34,6 +34,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)
@@ -48,7 +76,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

@@ -93,6 +93,7 @@ Base.LibGit2.lookup_branch
 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