More docs for merge!

base/libgit2/merge.jl

@@ -111,6 +111,29 @@ function ffmerge!(repo::GitRepo, ann::GitAnnotated)
 end
 
 # Merge changes into current head
+"""
+    merge!(repo::GitRepo, anns::Vector{GitAnnotated}; kwargs...) -> Bool
+
+Merge changes from the annotated commits (captured as [`GitAnnotated`](@ref) objects)
+`anns` into the HEAD of the repository `repo`. The keyword arguments are:
+  * `merge_opts::MergeOptions = MergeOptions()`: options for how to perform the merge,
+    including whether fastforwarding is allowed. See [`MergeOptions`](@ref) for more
+    information.
+  * `checkout_opts::CheckoutOptions = CheckoutOptions()`: options for how to perform
+    the checkout. See [`CheckoutOptions`](@ref) for more information.
+
+`anns` may refer to remote or local branch heads. Return `true` if the merge is
+successful, otherwise return `false` (for instance, if no merge is possible
+because the branches have no common ancestor).
+
+# Examples
+```julia
+upst_ann = LibGit2.GitAnnotated(repo, "branch/a")
+
+# merge the branch in
+LibGit2.merge!(repo, [upst_ann])
+```
+"""
 function merge!(repo::GitRepo, anns::Vector{GitAnnotated};
                 merge_opts::MergeOptions = MergeOptions(),
                 checkout_opts::CheckoutOptions = CheckoutOptions())
@@ -126,6 +149,40 @@ end
 
 # Internal implementation of merge.
 # Returns `true` if merge was successful, otherwise `false`
+"""
+    merge!(repo::GitRepo, anns::Vector{GitAnnotated}, fastforward::Bool; kwargs...) -> Bool
+
+Merge changes from the annotated commits (captured as [`GitAnnotated`](@ref) objects)
+`anns` into the HEAD of the repository `repo`. If `fastforward` is `true`, *only* a
+fastforward merge is allowed. In this case, if conflicts occur, the merge will fail.
+Otherwise, if `fastforward` is `false`, the merge may produce a conflict file which
+the user will need to resolve.
+
+The keyword arguments are:
+  * `merge_opts::MergeOptions = MergeOptions()`: options for how to perform the merge,
+    including whether fastforwarding is allowed. See [`MergeOptions`](@ref) for more
+    information.
+  * `checkout_opts::CheckoutOptions = CheckoutOptions()`: options for how to perform
+    the checkout. See [`CheckoutOptions`](@ref) for more information.
+
+`anns` may refer to remote or local branch heads. Return `true` if the merge is
+successful, otherwise return `false` (for instance, if no merge is possible
+because the branches have no common ancestor).
+
+# Examples
+```julia
+upst_ann_1 = LibGit2.GitAnnotated(repo, "branch/a")
+
+# merge the branch in, fastforward
+LibGit2.merge!(repo, [upst_ann_1], true)
+
+# merge conflicts!
+upst_ann_2 = LibGit2.GitAnnotated(repo, "branch/b")
+# merge the branch in, try to fastforward
+LibGit2.merge!(repo, [upst_ann_2], true) # will return false
+LibGit2.merge!(repo, [upst_ann_2], false) # will return true
+```
+"""
 function merge!(repo::GitRepo, anns::Vector{GitAnnotated}, fastforward::Bool;
                 merge_opts::MergeOptions = MergeOptions(),
                 checkout_opts::CheckoutOptions = CheckoutOptions())

doc/src/devdocs/libgit2.md

@@ -24,6 +24,7 @@ Base.LibGit2.DiffFile
 Base.LibGit2.DiffOptionsStruct
 Base.LibGit2.FetchHead
 Base.LibGit2.FetchOptions
+Base.LibGit2.GitAnnotated
 Base.LibGit2.GitBlame
 Base.LibGit2.GitBlob
 Base.LibGit2.GitCommit
@@ -82,6 +83,8 @@ Base.LibGit2.fetch_refspecs
 Base.LibGit2.fetchhead_foreach_cb
 Base.LibGit2.merge_base
 Base.LibGit2.merge!(::Base.LibGit2.GitRepo; ::Any...)
+Base.LibGit2.merge!(::Base.LibGit2.GitRepo, ::Vector{Base.LibGit2.GitAnnotated}; ::Base.LibGit2.MergeOptions, ::Base.LibGit2.CheckoutOptions)
+Base.LibGit2.merge!(::Base.LibGit2.GitRepo, ::Vector{Base.LibGit2.GitAnnotated}, ::Bool; ::Base.LibGit2.MergeOptions, ::Base.LibGit2.CheckoutOptions)
 Base.LibGit2.ffmerge!
 Base.LibGit2.fullname
 Base.LibGit2.features