Introduce repo.Describe()

Author: nulltoken

LibGit2Sharp.Tests/DescribeFixture.cs

@@ -0,0 +1,53 @@
+using System.Linq;
+using LibGit2Sharp.Tests.TestHelpers;
+using Xunit;
+
+namespace LibGit2Sharp.Tests
+{
+    public class DescribeFixture : BaseFixture
+    {
+        [Fact]
+        public void CanDescribeACommit()
+        {
+            string path = SandboxBareTestRepo();
+            using (var repo = new Repository(path))
+            {
+                // No annotated tags can be used to describe "master"
+                var masterTip = repo.Branches["master"].Tip;
+                Assert.Throws<NotFoundException>(() => repo.Describe(masterTip));
+                Assert.Equal("4c062a6", repo.Describe(masterTip,
+                    new DescribeOptions { UseCommitIdAsFallback = true }));
+                Assert.Equal("4c06", repo.Describe(masterTip,
+                    new DescribeOptions { UseCommitIdAsFallback = true, MinimumCommitIdAbbreviatedSize = 2 }));
+
+                // No lightweight tags can either be used to describe "master"
+                Assert.Throws<NotFoundException>(() => repo.Describe(masterTip,
+                    new DescribeOptions{ Strategy = DescribeStrategy.Tags }));
+
+                repo.ApplyTag("myTag", "5b5b025afb0b4c913b4c338a42934a3863bf3644");
+                Assert.Equal("myTag-5-g4c062a6", repo.Describe(masterTip,
+                    new DescribeOptions { Strategy = DescribeStrategy.Tags }));
+                Assert.Equal("myTag-5-g4c062a636", repo.Describe(masterTip,
+                    new DescribeOptions { Strategy = DescribeStrategy.Tags, MinimumCommitIdAbbreviatedSize = 9 }));
+                Assert.Equal("myTag-4-gbe3563a", repo.Describe(masterTip.Parents.Single(),
+                    new DescribeOptions { Strategy = DescribeStrategy.Tags }));
+
+                Assert.Equal("heads/master", repo.Describe(masterTip,
+                    new DescribeOptions { Strategy = DescribeStrategy.All }));
+                Assert.Equal("heads/packed-test-3-gbe3563a", repo.Describe(masterTip.Parents.Single(),
+                    new DescribeOptions { Strategy = DescribeStrategy.All }));
+
+                // "test" branch points to an annotated tag (also named "test")
+                // Let's rename the branch to ease the understanding of what we
+                // are exercising.
+
+                repo.Branches.Rename(repo.Branches["test"], "ForLackOfABetterName");
+
+                var anotherTip = repo.Branches["ForLackOfABetterName"].Tip;
+                Assert.Equal("test", repo.Describe(anotherTip));
+                Assert.Equal("test-0-g7b43849", repo.Describe(anotherTip,
+                    new DescribeOptions{ AlwaysRenderLongFormat = true }));
+            }
+        }
+    }
+}

LibGit2Sharp.Tests/LibGit2Sharp.Tests.csproj

@@ -53,6 +53,7 @@
     <Compile Include="ArchiveTarFixture.cs" />
     <Compile Include="CheckoutFixture.cs" />
     <Compile Include="CherryPickFixture.cs" />
+    <Compile Include="DescribeFixture.cs" />
     <Compile Include="GlobalSettingsFixture.cs" />
     <Compile Include="PatchStatsFixture.cs" />
     <Compile Include="RefSpecFixture.cs" />

LibGit2Sharp/Core/Ensure.cs

@@ -198,6 +198,21 @@ public static void ArgumentConformsTo<T>(T argumentValue, Func<T, bool> checker,
             throw new ArgumentException(argumentName);
         }
 
+        /// <summary>
+        /// Checks an argument is a positive integer.
+        /// </summary>
+        /// <param name="argumentValue">The argument value to check.</param>
+        /// <param name="argumentName">The name of the argument.</param>
+        public static void ArgumentPositiveInt32(long argumentValue, string argumentName)
+        {
+            if (argumentValue >= 0 && argumentValue <= uint.MaxValue)
+            {
+                return;
+            }
+
+            throw new ArgumentException(argumentName);
+        }
+
         /// <summary>
         /// Check that the result of a C call that returns a non-null GitObject
         /// using the default exception builder.

LibGit2Sharp/Core/GitDescribeFormatOptions.cs

@@ -0,0 +1,25 @@
+using System;
+using System.Runtime.InteropServices;
+
+namespace LibGit2Sharp.Core
+{
+    [StructLayout(LayoutKind.Sequential)]
+    internal struct GitDescribeFormatOptions
+    {
+        public uint Version;
+        public uint MinAbbreviatedSize;
+        public bool AlwaysUseLongFormat;
+        public IntPtr DirtySuffix;
+    }
+
+    [StructLayout(LayoutKind.Sequential)]
+    internal struct GitDescribeOptions
+    {
+        public uint Version;
+        public uint MaxCandidatesTags;
+        public DescribeStrategy DescribeStrategy;
+        public IntPtr Pattern;
+        public bool OnlyFollowFirstParent;
+        public bool ShowCommitOidAsFallback;
+    }
+}

LibGit2Sharp/Core/Handles/DescribeResultSafeHandle.cs

@@ -0,0 +1,11 @@
+namespace LibGit2Sharp.Core.Handles
+{
+    internal class DescribeResultSafeHandle : SafeHandleBase
+    {
+        protected override bool ReleaseHandleImpl()
+        {
+            Proxy.git_describe_free(handle);
+            return true;
+        }
+    }
+}

LibGit2Sharp/Core/NativeMethods.cs

@@ -422,6 +422,21 @@ internal static extern int git_cred_userpass_plaintext_new(
             [MarshalAs(UnmanagedType.CustomMarshaler, MarshalCookie = UniqueId.UniqueIdentifier, MarshalTypeRef = typeof (StrictUtf8Marshaler))] string username,
             [MarshalAs(UnmanagedType.CustomMarshaler, MarshalCookie = UniqueId.UniqueIdentifier, MarshalTypeRef = typeof (StrictUtf8Marshaler))] string password);
 
+        [DllImport(libgit2)]
+        internal static extern int git_describe_commit(
+            out DescribeResultSafeHandle describe,
+            GitObjectSafeHandle committish,
+            ref GitDescribeOptions options);
+
+        [DllImport(libgit2)]
+        internal static extern int git_describe_format(
+            GitBuf buf,
+            DescribeResultSafeHandle describe,
+            ref GitDescribeFormatOptions options);
+
+        [DllImport(libgit2)]
+        internal static extern void git_describe_result_free(IntPtr describe);
+
         [DllImport(libgit2)]
         internal static extern void git_diff_free(IntPtr diff);
 

LibGit2Sharp/Core/Proxy.cs

@@ -608,6 +608,68 @@ public static ConfigurationSafeHandle git_config_snapshot(ConfigurationSafeHandl
 
         #endregion
 
+        #region git_describe_
+
+        public static string git_describe_commit(
+            RepositorySafeHandle repo,
+            ObjectId committishId,
+            DescribeOptions options)
+        {
+            Ensure.ArgumentPositiveInt32(options.MinimumCommitIdAbbreviatedSize,
+                "options.MinimumCommitIdAbbreviatedSize");
+
+            using (ThreadAffinity())
+            using (var osw = new ObjectSafeWrapper(committishId, repo))
+            {
+                GitDescribeOptions opts = new GitDescribeOptions
+                {
+                    Version = 1,
+                    DescribeStrategy = options.Strategy,
+                    MaxCandidatesTags = 10,
+                    OnlyFollowFirstParent = false,
+                    ShowCommitOidAsFallback = options.UseCommitIdAsFallback,
+                };
+
+                DescribeResultSafeHandle describeHandle = null;
+
+                try
+                {
+                    int res = NativeMethods.git_describe_commit(out describeHandle, osw.ObjectPtr, ref opts);
+                    Ensure.ZeroResult(res);
+
+                    using (var buf = new GitBuf())
+                    {
+                        GitDescribeFormatOptions formatOptions = new GitDescribeFormatOptions
+                        {
+                            Version = 1,
+                            MinAbbreviatedSize = (uint)options.MinimumCommitIdAbbreviatedSize,
+                            AlwaysUseLongFormat = options.AlwaysRenderLongFormat,
+                        };
+
+                        res = NativeMethods.git_describe_format(buf, describeHandle, ref formatOptions);
+                        Ensure.ZeroResult(res);
+
+                        describeHandle.Dispose();
+                        return LaxUtf8Marshaler.FromNative(buf.ptr);
+                    }
+                }
+                finally
+                {
+                    if (describeHandle != null)
+                    {
+                        describeHandle.Dispose();
+                    }
+                }
+            }
+        }
+
+        public static void git_describe_free(IntPtr iter)
+        {
+            NativeMethods.git_describe_result_free(iter);
+        }
+
+        #endregion
+
         #region git_diff_
 
         public static void git_diff_blobs(

LibGit2Sharp/DescribeOptions.cs

@@ -0,0 +1,58 @@
+namespace LibGit2Sharp
+{
+    /// <summary>
+    /// Options to define describe behaviour
+    /// </summary>
+    public sealed class DescribeOptions
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="DescribeOptions"/> class.
+        /// <para>
+        ///   By default:
+        ///    - Only annotated tags will be considered as reference points
+        ///    - The commit id won't be used as a fallback strategy
+        ///    - Only the 10 most recent tags will be considered as candidates to describe the commit
+        ///    - All ancestor lines will be followed upon seeing a merge commit
+        ///    - 7 hexacidemal digits will be used as a minimum commid abbreviated size
+        ///    - Long format will only be used when no direct match has been found
+        /// </para>
+        /// </summary>
+        public DescribeOptions()
+        {
+            Strategy = DescribeStrategy.Default;
+            MinimumCommitIdAbbreviatedSize = 7;
+        }
+
+        /// <summary>
+        /// The kind of references that will be eligible as reference points.
+        /// </summary>
+        public DescribeStrategy Strategy { get; set; }
+
+        /// <summary>
+        /// Rather than throwing, should <see cref="IRepository.Describe"/> return
+        /// the abbreviated commit id when the selected <see cref="Strategy"/>
+        /// didn't identify a proper reference to describe the commit.
+        /// </summary>
+        public bool UseCommitIdAsFallback { get; set; }
+
+        /// <summary>
+        /// Number of minimum hexadecimal digits used to render a uniquely
+        /// abbreviated commit id.
+        /// </summary>
+        public int MinimumCommitIdAbbreviatedSize { get; set; }
+
+        /// <summary>
+        /// Always output the long format (the tag, the number of commits
+        /// and the abbreviated commit name) even when a direct match has been
+        /// found.
+        /// <para>
+        ///   This is useful when one wants to see parts of the commit object
+        ///   name in "describe" output, even when the commit in question happens
+        ///   to be a tagged version. Instead of just emitting the tag name, it
+        ///   will describe such a commit as v1.2-0-gdeadbee (0th commit since
+        ///   tag v1.2 that points at object deadbee...).
+        /// </para>
+        /// </summary>
+        public bool AlwaysRenderLongFormat { get; set; }
+    }
+}

LibGit2Sharp/DescribeStrategy.cs

@@ -0,0 +1,30 @@
+namespace LibGit2Sharp
+{
+    /// <summary>
+    /// Specify the kind of committish which will be considered
+    /// when trying to identify the closest reference to the described commit.
+    /// </summary>
+    public enum DescribeStrategy
+    {
+        /// <summary>
+        /// Only consider annotated tags.
+        /// </summary>
+        Default = 0,
+
+        /// <summary>
+        /// Consider both annotated and lightweight tags.
+        /// <para>
+        ///   This will match every reference under the <code>refs/tags/</code> namespace.
+        /// </para>
+        /// </summary>
+        Tags,
+
+        /// <summary>
+        /// Consider annotated and lightweight tags, local and remote tracking branches.
+        /// <para>
+        ///   This will match every reference under the <code>refs/</code> namespace.
+        /// </para>
+        /// </summary>
+        All,
+    }
+}

LibGit2Sharp/IRepository.cs

@@ -365,5 +365,23 @@ public interface IRepository : IDisposable
         /// <param name="options">If set, the options that control the status investigation.</param>
         /// <returns>A <see cref="RepositoryStatus"/> holding the state of all the files.</returns>
         RepositoryStatus RetrieveStatus(StatusOptions options);
+
+        /// <summary>
+        /// Finds the most recent annotated tag that is reachable from a commit.
+        /// <para>
+        ///   If the tag points to the commit, then only the tag is shown. Otherwise,
+        ///   it suffixes the tag name with the number of additional commits on top
+        ///   of the tagged object and the abbreviated object name of the most recent commit.
+        /// </para>
+        /// <para>
+        ///   Optionally, the <paramref name="options"/> parameter allow to tweak the
+        ///   search strategy (considering lightweith tags, or even branches as reference points)
+        ///   and the formatting of the returned identifier.
+        /// </para>
+        /// </summary>
+        /// <param name="commit">The commit to be described.</param>
+        /// <param name="options">Determines how the commit will be described.</param>
+        /// <returns>A descriptive identifier for the commit based on the nearest annotated tag.</returns>
+        string Describe(Commit commit, DescribeOptions options);
     }
 }

LibGit2Sharp/LibGit2Sharp.csproj

@@ -68,8 +68,12 @@
     <Compile Include="CommitOptions.cs" />
     <Compile Include="CommitSortStrategies.cs" />
     <Compile Include="CompareOptions.cs" />
+    <Compile Include="DescribeOptions.cs" />
+    <Compile Include="DescribeStrategy.cs" />
+    <Compile Include="Core\GitDescribeFormatOptions.cs" />
     <Compile Include="Core\GitIndexReucEntry.cs" />
     <Compile Include="Core\GitSubmoduleOptions.cs" />
+    <Compile Include="Core\Handles\DescribeResultSafeHandle.cs" />
     <Compile Include="Core\Handles\IndexNameEntrySafeHandle.cs" />
     <Compile Include="Core\Handles\IndexReucEntrySafeHandle.cs" />
     <Compile Include="EntryExistsException.cs" />

LibGit2Sharp/Repository.cs

@@ -1891,6 +1891,30 @@ private IEnumerable<string> RemoveStagedItems(IEnumerable<string> paths, bool re
             return removed;
         }
 
+        /// <summary>
+        /// Finds the most recent annotated tag that is reachable from a commit.
+        /// <para>
+        ///   If the tag points to the commit, then only the tag is shown. Otherwise,
+        ///   it suffixes the tag name with the number of additional commits on top
+        ///   of the tagged object and the abbreviated object name of the most recent commit.
+        /// </para>
+        /// <para>
+        ///   Optionally, the <paramref name="options"/> parameter allow to tweak the
+        ///   search strategy (considering lightweith tags, or even branches as reference points)
+        ///   and the formatting of the returned identifier.
+        /// </para>
+        /// </summary>
+        /// <param name="commit">The commit to be described.</param>
+        /// <param name="options">Determines how the commit will be described.</param>
+        /// <returns>A descriptive identifier for the commit based on the nearest annotated tag.</returns>
+        public string Describe(Commit commit, DescribeOptions options)
+        {
+            Ensure.ArgumentNotNull(commit, "commit");
+            Ensure.ArgumentNotNull(options, "options");
+
+            return Proxy.git_describe_commit(handle, commit.Id, options);
+        }
+
         private string DebuggerDisplay
         {
             get

LibGit2Sharp/RepositoryExtensions.cs

@@ -738,5 +738,21 @@ public static RepositoryStatus RetrieveStatus(this IRepository repository)
             Proxy.git_index_read(repository.Index.Handle);
             return new RepositoryStatus((Repository)repository, null);
         }
+
+        /// <summary>
+        /// Finds the most recent annotated tag that is reachable from a commit.
+        /// <para>
+        ///   If the tag points to the commit, then only the tag is shown. Otherwise,
+        ///   it suffixes the tag name with the number of additional commits on top
+        ///   of the tagged object and the abbreviated object name of the most recent commit.
+        /// </para>
+        /// </summary>
+        /// <param name="repository">The <see cref="IRepository"/> being worked with.</param>
+        /// <param name="commit">The commit to be described.</param>
+        /// <returns>A descriptive identifier for the commit based on the nearest annotated tag.</returns>
+        public static string Describe(this IRepository repository, Commit commit)
+        {
+            return repository.Describe(commit, new DescribeOptions());
+        }
     }
 }