Introduce Repository.MergeFetchedRefs

Make `Repository.MergeFetchHeads` public (with a slightly less
scary sounding name) so that a consumer may perform the mechanics
of a `Pull` in two steps.

Author: Edward Thomson

LibGit2Sharp.Tests/NetworkFixture.cs

@@ -228,6 +228,33 @@ public void PullWithoutMergeBranchThrows()
             }
         }
 
+        [Fact]
+        public void CanMergeFetchedRefs()
+        {
+            string url = "https://github.com/libgit2/TestGitRepository";
+
+            var scd = BuildSelfCleaningDirectory();
+            string clonedRepoPath = Repository.Clone(url, scd.DirectoryPath);
+
+            using (var repo = new Repository(clonedRepoPath))
+            {
+                repo.Reset(ResetMode.Hard, "HEAD~1");
+
+                Assert.False(repo.RetrieveStatus().Any());
+                Assert.Equal(repo.Lookup<Commit>("refs/remotes/origin/master~1"), repo.Head.Tip);
+
+                repo.Network.Fetch(repo.Head.Remote);
+
+                MergeOptions mergeOptions = new MergeOptions()
+                {
+                    FastForwardStrategy = FastForwardStrategy.NoFastFoward
+                };
+
+                MergeResult mergeResult = repo.MergeFetchedRefs(Constants.Signature, mergeOptions);
+                Assert.Equal(mergeResult.Status, MergeStatus.NonFastForward);
+            }
+        }
+
         /*
         * git ls-remote http://github.com/libgit2/TestGitRepository
         * 49322bb17d3acc9146f98c97d078513228bbf3c0        HEAD

LibGit2Sharp/IRepository.cs

@@ -222,6 +222,18 @@ public interface IRepository : IDisposable
         /// <returns>The <see cref="MergeResult"/> of the merge.</returns>
         MergeResult Merge(string committish, Signature merger, MergeOptions options);
 
+        /// <summary>
+        /// Merge the reference that was recently fetched. This will merge
+        /// the branch on the fetched remote that corresponded to the
+        /// current local branch when we did the fetch. This is the
+        /// second step in performing a pull operation (after having
+        /// performed said fetch).
+        /// </summary>
+        /// <param name="merger">The <see cref="Signature"/> of who is performing the merge.</param>
+        /// <param name="options">Specifies optional parameters controlling merge behavior; if null, the defaults are used.</param>
+        /// <returns>The <see cref="MergeResult"/> of the merge.</returns>
+        MergeResult MergeFetchedRefs(Signature merger, MergeOptions options);
+
         /// <summary>
         /// Cherry picks changes from the commit into the branch pointed at by HEAD.
         /// </summary>

LibGit2Sharp/Network.cs

@@ -306,7 +306,7 @@ public virtual MergeResult Pull(Signature merger, PullOptions options)
             }
 
             Fetch(currentBranch.Remote, options.FetchOptions);
-            return repository.MergeFetchHeads(merger, options.MergeOptions);
+            return repository.MergeFetchedRefs(merger, options.MergeOptions);
         }
 
         /// <summary>

LibGit2Sharp/Repository.cs

@@ -1040,12 +1040,16 @@ public MergeResult Merge(string committish, Signature merger, MergeOptions optio
         }
 
         /// <summary>
-        /// Merge the current fetch heads into the branch pointed at by HEAD.
+        /// Merge the reference that was recently fetched. This will merge
+        /// the branch on the fetched remote that corresponded to the
+        /// current local branch when we did the fetch.  This is the
+        /// second step in performing a pull operation (after having
+        /// performed said fetch).
         /// </summary>
         /// <param name="merger">The <see cref="Signature"/> of who is performing the merge.</param>
         /// <param name="options">Specifies optional parameters controlling merge behavior; if null, the defaults are used.</param>
         /// <returns>The <see cref="MergeResult"/> of the merge.</returns>
-        internal MergeResult MergeFetchHeads(Signature merger, MergeOptions options)
+        public MergeResult MergeFetchedRefs(Signature merger, MergeOptions options)
         {
             Ensure.ArgumentNotNull(merger, "merger");