Implement, test, doc git descriptions for things (JuliaLang#20885)

* Add GitDescribe functions and tests

* Add docs for new functions

* "git-describe" => "git describe"

* Fix hypen

base/libgit2/consts.jl

@@ -201,6 +201,11 @@ module Consts
     const CLONE_NO_LOCAL       = Cint(2)
     const CLONE_LOCAL_NO_LINKS = Cint(3)
 
+    # describe
+    const DESCRIBE_DEFAULT = Cuint(0)
+    const DESCRIBE_TAGS    = Cuint(1 << 0)
+    const DESCRIBE_ALL     = Cuint(1 << 1)
+
     # status
     const STATUS_CURRENT          = Cuint(0)
     const STATUS_INDEX_NEW        = Cuint(1 << 0)

base/libgit2/repository.jl

@@ -227,6 +227,69 @@ function peel(::Type{T}, obj::GitObject) where T<:GitObject
 end
 peel(obj::GitObject) = peel(GitObject, obj)
 
+"""
+    LibGit2.GitDescribeResult(commitish::GitObject; kwarg...)
+
+Produce a `GitDescribeResult` of the `commitish` `GitObject`, which
+contains detailed information about it based on the keyword argument:
+
+  * `options::DescribeOptions=DescribeOptions()`
+
+Equivalent to `git describe <commitish>`.
+"""
+function GitDescribeResult(commitish::GitObject;
+                           options::DescribeOptions=DescribeOptions())
+    result_ptr_ptr = Ref{Ptr{Void}}(C_NULL)
+    @check ccall((:git_describe_commit, :libgit2), Cint,
+                 (Ptr{Ptr{Void}}, Ptr{Void}, Ptr{DescribeOptions}),
+                 result_ptr_ptr, commitish.ptr, Ref(options))
+    return GitDescribeResult(commitish.owner, result_ptr_ptr[])
+end
+
+"""
+    LibGit2.GitDescribeResult(repo::GitRepo; kwarg...)
+
+Produce a `GitDescribeResult` of the repository `repo`'s working directory,
+which can include all the commits and tags (or, for instance, HEAD only).
+The `GitDescribeResult` contains detailed information about the workdir based
+on the keyword argument:
+
+  * `options::DescribeOptions=DescribeOptions()`
+
+Equivalent to `git describe`.
+"""
+function GitDescribeResult(repo::GitRepo; options::DescribeOptions=DescribeOptions())
+    result_ptr_ptr = Ref{Ptr{Void}}(C_NULL)
+    @check ccall((:git_describe_workdir, :libgit2), Cint,
+                 (Ptr{Ptr{Void}}, Ptr{Void}, Ptr{DescribeOptions}),
+                 result_ptr_ptr, repo.ptr, Ref(options))
+    return GitDescribeResult(repo, result_ptr_ptr[])
+end
+
+"""
+    LibGit2.format(result::GitDescribeResult; kwarg...) -> String
+
+Produce a formatted string based on a `GitDescribeResult`.
+Formatting options are controlled by the keyword argument:
+
+  * `options::DescribeFormatOptions=DescribeFormatOptions()`
+"""
+function format(result::GitDescribeResult; options::DescribeFormatOptions=DescribeFormatOptions())
+    buf_ref = Ref(Buffer())
+    @check ccall((:git_describe_format, :libgit2), Cint,
+                 (Ptr{Buffer}, Ptr{Void}, Ptr{DescribeFormatOptions}),
+                 buf_ref, result.ptr, Ref(options))
+    buf = buf_ref[]
+    str = unsafe_string(buf.ptr, buf.size)
+    free(buf_ref)
+    return str
+end
+
+function Base.show(io::IO, result::GitDescribeResult)
+    fmt_desc = format(result)
+    println(io, "GitDescribeResult:")
+    println(io, fmt_desc)
+end
 
 function checkout_tree(repo::GitRepo, obj::GitObject;
                        options::CheckoutOptions = CheckoutOptions())

base/libgit2/types.jl

@@ -270,6 +270,33 @@ Matches the [`git_diff_options`](https://libgit2.github.com/libgit2/#HEAD/type/g
     new_prefix::Cstring
 end
 
+"""
+    LibGit2.DescribeOptions
+
+Matches the [`git_describe_options`](https://libgit2.github.com/libgit2/#HEAD/type/git_describe_options) struct.
+"""
+@kwdef struct DescribeOptions
+    version::Cuint             = 1
+    max_candidates_tags::Cuint = 10
+    describe_strategy::Cuint   = Consts.DESCRIBE_DEFAULT
+
+    pattern::Cstring
+    only_follow_first_parent::Cint
+    show_commit_oid_as_fallback::Cint
+end
+
+"""
+    LibGit2.DescribeFormatOptions
+
+Matches the [`git_describe_format_options`](https://libgit2.github.com/libgit2/#HEAD/type/git_describe_format_options) struct.
+"""
+@kwdef struct DescribeFormatOptions
+    version::Cuint          = 1
+    abbreviated_size::Cuint = 7
+    always_use_long_format::Cint
+    dirty_suffix::Cstring
+end
+
 """
     LibGit2.DiffFile
 
@@ -496,24 +523,25 @@ Base.isempty(obj::AbstractGitObject) = (obj.ptr == C_NULL)
 abstract type GitObject <: AbstractGitObject end
 
 for (typ, owntyp, sup, cname) in [
-    (:GitRepo,          nothing,               :AbstractGitObject, :git_repository),
-    (:GitConfig,        :(Nullable{GitRepo}),  :AbstractGitObject, :git_config),
-    (:GitIndex,         :(Nullable{GitRepo}),  :AbstractGitObject, :git_index),
-    (:GitRemote,        :GitRepo,              :AbstractGitObject, :git_remote),
-    (:GitRevWalker,     :GitRepo,              :AbstractGitObject, :git_revwalk),
-    (:GitReference,     :GitRepo,              :AbstractGitObject, :git_reference),
-    (:GitDiff,          :GitRepo,              :AbstractGitObject, :git_diff),
-    (:GitDiffStats,     :GitRepo,              :AbstractGitObject, :git_diff_stats),
-    (:GitAnnotated,     :GitRepo,              :AbstractGitObject, :git_annotated_commit),
-    (:GitRebase,        :GitRepo,              :AbstractGitObject, :git_rebase),
-    (:GitStatus,        :GitRepo,              :AbstractGitObject, :git_status_list),
-    (:GitBranchIter,    :GitRepo,              :AbstractGitObject, :git_branch_iterator),
-    (:GitUnknownObject, :GitRepo,              :GitObject,         :git_object),
-    (:GitCommit,        :GitRepo,              :GitObject,         :git_commit),
-    (:GitBlob,          :GitRepo,              :GitObject,         :git_blob),
-    (:GitTree,          :GitRepo,              :GitObject,         :git_tree),
-    (:GitTag,           :GitRepo,              :GitObject,         :git_tag),
-    (:GitTreeEntry,     :GitTree,              :AbstractGitObject, :git_tree_entry),
+    (:GitRepo,           nothing,               :AbstractGitObject, :git_repository),
+    (:GitConfig,         :(Nullable{GitRepo}),  :AbstractGitObject, :git_config),
+    (:GitIndex,          :(Nullable{GitRepo}),  :AbstractGitObject, :git_index),
+    (:GitRemote,         :GitRepo,              :AbstractGitObject, :git_remote),
+    (:GitRevWalker,      :GitRepo,              :AbstractGitObject, :git_revwalk),
+    (:GitReference,      :GitRepo,              :AbstractGitObject, :git_reference),
+    (:GitDescribeResult, :GitRepo,              :AbstractGitObject, :git_describe_result),
+    (:GitDiff,           :GitRepo,              :AbstractGitObject, :git_diff),
+    (:GitDiffStats,      :GitRepo,              :AbstractGitObject, :git_diff_stats),
+    (:GitAnnotated,      :GitRepo,              :AbstractGitObject, :git_annotated_commit),
+    (:GitRebase,         :GitRepo,              :AbstractGitObject, :git_rebase),
+    (:GitStatus,         :GitRepo,              :AbstractGitObject, :git_status_list),
+    (:GitBranchIter,     :GitRepo,              :AbstractGitObject, :git_branch_iterator),
+    (:GitUnknownObject,  :GitRepo,              :GitObject,         :git_object),
+    (:GitCommit,         :GitRepo,              :GitObject,         :git_commit),
+    (:GitBlob,           :GitRepo,              :GitObject,         :git_blob),
+    (:GitTree,           :GitRepo,              :GitObject,         :git_tree),
+    (:GitTag,            :GitRepo,              :GitObject,         :git_tag),
+    (:GitTreeEntry,      :GitTree,              :AbstractGitObject, :git_tree_entry),
     ]
 
     if owntyp === nothing

test/libgit2.jl

@@ -440,7 +440,6 @@ mktempdir() do dir
                     @test contains(showstr[4], "SHA:")
                     @test showstr[5] == "Message:"
                     @test showstr[6] == commit_msg1
-
                     @test LibGit2.revcount(repo, string(commit_oid1), string(commit_oid3)) == (-1,0)
                 finally
                     close(cmt)
@@ -560,6 +559,15 @@ mktempdir() do dir
                 @test length(tags) == 1
                 @test tag2 ∈ tags
                 @test tag1 ∉ tags
+
+                description = LibGit2.GitDescribeResult(repo)
+                fmtted_description = LibGit2.format(description)
+                @test sprint(show, description) == "GitDescribeResult:\n$fmtted_description\n"
+                @test fmtted_description == "tag2"
+                description = LibGit2.GitDescribeResult(LibGit2.GitObject(repo, "HEAD"))
+                fmtted_description = LibGit2.format(description)
+                @test sprint(show, description) == "GitDescribeResult:\n$fmtted_description\n"
+                @test fmtted_description == "tag2"
             finally
                 close(repo)
             end