Add DescribeOptions.OnlyFollowFirstParent property

The GitDescribeOptions struct used by git_describe_commit has an OnlyFollowFirstParent field, which corresponds to the --first-parent option in command-line Git.

This commit adds the same option as a new property on the DescribeOptions class, with XML documentation from Git docs.

Author: ninjeff

LibGit2Sharp.Tests/DescribeFixture.cs

@@ -1,6 +1,7 @@
 using System.Linq;
 using LibGit2Sharp.Tests.TestHelpers;
 using Xunit;
+using System;
 
 namespace LibGit2Sharp.Tests
 {
@@ -49,5 +50,35 @@ public void CanDescribeACommit()
                     new DescribeOptions{ AlwaysRenderLongFormat = true }));
             }
         }
+
+        [Fact]
+        public void CanFollowFirstParent()
+        {
+            string path = SandboxStandardTestRepo();
+            using (var repo = new Repository(path))
+            {
+                var branch = repo.CreateBranch("branch");
+
+                // Make an earlier tag on master
+                repo.Commit("A", Constants.Signature, Constants.Signature, new CommitOptions { AllowEmptyCommit = true });
+                repo.ApplyTag("firstParentTag");
+
+                // Make a later tag on branch
+                repo.Checkout(branch);
+                repo.Commit("B", Constants.Signature, Constants.Signature, new CommitOptions { AllowEmptyCommit = true });
+                repo.ApplyTag("mostRecentTag");
+
+                repo.Checkout("master");
+                repo.Commit("C", Constants.Signature, Constants.Signature, new CommitOptions { AllowEmptyCommit = true });
+                repo.Merge(branch, Constants.Signature, new MergeOptions() { FastForwardStrategy = FastForwardStrategy.NoFastForward });
+
+                // With OnlyFollowFirstParent = false, the most recent tag reachable should be returned
+                Assert.Equal("mostRecentTag-3-gf17be71", repo.Describe(repo.Head.Tip, new DescribeOptions { OnlyFollowFirstParent = false, Strategy = DescribeStrategy.Tags }));
+
+                // With OnlyFollowFirstParent = true, the most recent tag on the current branch should be returned
+                Assert.Equal("firstParentTag-2-gf17be71", repo.Describe(repo.Head.Tip, new DescribeOptions { OnlyFollowFirstParent = true, Strategy = DescribeStrategy.Tags }));
+
+            }
+        }
     }
 }

LibGit2Sharp/Core/Proxy.cs

@@ -644,7 +644,7 @@ public static string git_describe_commit(
                     Version = 1,
                     DescribeStrategy = options.Strategy,
                     MaxCandidatesTags = 10,
-                    OnlyFollowFirstParent = false,
+                    OnlyFollowFirstParent = options.OnlyFollowFirstParent,
                     ShowCommitOidAsFallback = options.UseCommitIdAsFallback,
                 };
 

LibGit2Sharp/DescribeOptions.cs

@@ -21,6 +21,7 @@ public DescribeOptions()
         {
             Strategy = DescribeStrategy.Default;
             MinimumCommitIdAbbreviatedSize = 7;
+            OnlyFollowFirstParent = false;
         }
 
         /// <summary>
@@ -54,5 +55,14 @@ public DescribeOptions()
         /// </para>
         /// </summary>
         public bool AlwaysRenderLongFormat { get; set; }
+
+        /// <summary>
+        /// Follow only the first parent commit upon seeing a merge commit.
+        /// <para>
+        ///   This is useful when you wish to not match tags on branches merged in
+        ///   the history of the target commit.
+        /// </para>
+        /// </summary>
+        public bool OnlyFollowFirstParent { get; set; }
     }
 }