From 144c46be0ad98bc0dd40b3e3c5783b1cb12d2f92 Mon Sep 17 00:00:00 2001 From: Katharine Hyatt Date: Mon, 28 Aug 2017 14:22:55 -0700 Subject: [PATCH] Make describe docs more accurate/informative (#23477) * Make describe docs more accurate/informative --- base/libgit2/repository.jl | 22 ++++++++++++++++++---- doc/src/devdocs/libgit2.md | 2 ++ 2 files changed, 20 insertions(+), 4 deletions(-) diff --git a/base/libgit2/repository.jl b/base/libgit2/repository.jl index 38a326f5b6823..4f169add16115 100644 --- a/base/libgit2/repository.jl +++ b/base/libgit2/repository.jl @@ -251,7 +251,16 @@ contains detailed information about it based on the keyword argument: * `options::DescribeOptions=DescribeOptions()` -Equivalent to `git describe `. +A git decription of a `commitish` object looks for the tag (by default, annotated, +although a search of all tags can be performed) which can be reached from `commitish` +which is most recent. If the tag is pointing to `commitish`, then only the tag is +included in the description. Otherwise, a suffix is included which contains the +number of commits between `commitish` and the most recent tag. If there is no such +tag, the default behavior is for the description to fail, although this can be +changed through `options`. + +Equivalent to `git describe `. See [`DescribeOptions`](@ref) for more +information. """ function GitDescribeResult(commitish::GitObject; options::DescribeOptions=DescribeOptions()) @@ -265,14 +274,19 @@ 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). +Produce a `GitDescribeResult` of the repository `repo`'s working directory. The `GitDescribeResult` contains detailed information about the workdir based on the keyword argument: * `options::DescribeOptions=DescribeOptions()` -Equivalent to `git describe`. +In this case, the description is run on HEAD, producing the most recent tag +which is an ancestor of HEAD. Afterwards, a status check on +the [`workdir`](@ref) is performed and if the `workdir` is dirty +(see [`isdirty`](@ref)) the description is also considered dirty. + +Equivalent to `git describe`. See [`DescribeOptions`](@ref) for more +information. """ function GitDescribeResult(repo::GitRepo; options::DescribeOptions=DescribeOptions()) result_ptr_ptr = Ref{Ptr{Void}}(C_NULL) diff --git a/doc/src/devdocs/libgit2.md b/doc/src/devdocs/libgit2.md index b9b279d6a0eba..13709659c3c1f 100644 --- a/doc/src/devdocs/libgit2.md +++ b/doc/src/devdocs/libgit2.md @@ -17,6 +17,8 @@ Base.LibGit2.Buffer Base.LibGit2.CachedCredentials Base.LibGit2.CheckoutOptions Base.LibGit2.CloneOptions +Base.LibGit2.DescribeOptions +Base.LibGit2.DescribeFormatOptions Base.LibGit2.DiffDelta Base.LibGit2.DiffFile Base.LibGit2.DiffOptionsStruct