Add the UpstreamBranchCanonicalName property to Branch

This property contains the reference of the tracked branch, relatively to the upstream repository (so "refs/heads/master", and not "refs/remotes/origin/master").

Author: yorah

LibGit2Sharp.Tests/BranchFixture.cs

@@ -259,12 +259,13 @@ public void CanResolveRemote()
         }
 
         [Fact]
-        public void RemoteForNonTrackingBranchIsNull()
+        public void RemoteAndUpstreamBranchCanonicalNameForNonTrackingBranchIsNull()
         {
             using (var repo = new Repository(StandardTestRepoPath))
             {
                 Branch test = repo.Branches["i-do-numbers"];
                 Assert.Null(test.Remote);
+                Assert.Null(test.UpstreamBranchCanonicalName);
             }
         }
 
@@ -279,6 +280,16 @@ public void QueryRemoteForLocalTrackingBranch()
             }
         }
 
+        [Fact]
+        public void QueryUpstreamBranchCanonicalNameForLocalTrackingBranch()
+        {
+            using (var repo = new Repository(StandardTestRepoPath))
+            {
+                Branch trackLocal = repo.Branches["track-local"];
+                Assert.Equal("refs/heads/master", trackLocal.UpstreamBranchCanonicalName);
+            }
+        }
+
         [Fact]
         public void CanLookupABranchByItsCanonicalName()
         {
@@ -454,20 +465,20 @@ public void CanWalkCommitsFromAnotherBranch()
         }
 
         [Fact]
-        public void CanSetUpstreamBranch()
+        public void CanSetTrackedBranch()
         {
             const string testBranchName = "branchToSetUpstreamInfoFor";
-            const string upstreamBranchName = "refs/remotes/origin/master";
+            const string trackedBranchName = "refs/remotes/origin/master";
 
             string path = CloneStandardTestRepo();
             using (var repo = new Repository(path))
             {
                 Branch branch = repo.CreateBranch(testBranchName);
                 Assert.False(branch.IsTracking);
 
-                Branch upstreamBranch = repo.Branches[upstreamBranchName];
+                Branch trackedBranch = repo.Branches[trackedBranchName];
                 repo.Branches.Update(branch,
-                    b => b.Upstream = upstreamBranch.CanonicalName);
+                    b => b.TrackedBranch = trackedBranch.CanonicalName);
 
                 // Verify the immutability of the branch.
                 Assert.False(branch.IsTracking);
@@ -479,58 +490,59 @@ public void CanSetUpstreamBranch()
                 Assert.NotNull(upstreamRemote);
 
                 Assert.True(branch.IsTracking);
-                Assert.Equal(upstreamBranch, branch.TrackedBranch);
+                Assert.Equal(trackedBranch, branch.TrackedBranch);
                 Assert.Equal(upstreamRemote, branch.Remote);
             }
         }
 
         [Fact]
-        public void CanSetUpstreamMergeBranch()
+        public void CanSetUpstreamBranch()
         {
             const string testBranchName = "branchToSetUpstreamInfoFor";
-            const string mergeBranchName = "refs/heads/master";
-            const string upstreamBranchName = "refs/remotes/origin/master";
-            const string upstreamRemoteName = "origin";
+            const string upstreamBranchName = "refs/heads/master";
+            const string trackedBranchName = "refs/remotes/origin/master";
+            const string remoteName = "origin";
 
             string path = CloneStandardTestRepo();
             using (var repo = new Repository(path))
             {
                 Branch branch = repo.CreateBranch(testBranchName);
                 Assert.False(branch.IsTracking);
 
-                Branch upstreamBranch = repo.Branches[upstreamBranchName];
+                Branch trackedBranch = repo.Branches[trackedBranchName];
                 Branch updatedBranch = repo.Branches.Update(branch,
-                    b => b.UpstreamRemote = upstreamRemoteName,
-                    b => b.UpstreamMergeBranch =  mergeBranchName);
+                    b => b.Remote = remoteName,
+                    b => b.UpstreamBranch =  upstreamBranchName);
 
                 // Verify the immutability of the branch.
                 Assert.False(branch.IsTracking);
 
-                Remote upstreamRemote = repo.Network.Remotes[upstreamRemoteName];
+                Remote upstreamRemote = repo.Network.Remotes[remoteName];
                 Assert.NotNull(upstreamRemote);
 
                 Assert.True(updatedBranch.IsTracking);
-                Assert.Equal(upstreamBranch, updatedBranch.TrackedBranch);
+                Assert.Equal(trackedBranch, updatedBranch.TrackedBranch);
+                Assert.Equal(upstreamBranchName, updatedBranch.UpstreamBranchCanonicalName);
                 Assert.Equal(upstreamRemote, updatedBranch.Remote);
             }
         }
 
         [Fact]
-        public void CanSetLocalUpstreamBranch()
+        public void CanSetLocalTrackedBranch()
         {
             const string testBranchName = "branchToSetUpstreamInfoFor";
-            const string upstreamBranchName = "refs/heads/master";
+            const string localTrackedBranchName = "refs/heads/master";
 
             string path = CloneStandardTestRepo();
             using (var repo = new Repository(path))
             {
                 Branch branch = repo.CreateBranch(testBranchName);
                 Assert.False(branch.IsTracking);
 
-                Branch upstreamBranch = repo.Branches[upstreamBranchName];
+                Branch trackedBranch = repo.Branches[localTrackedBranchName];
 
                 repo.Branches.Update(branch,
-                    b => b.Upstream = upstreamBranch.CanonicalName);
+                    b => b.TrackedBranch = trackedBranch.CanonicalName);
 
                 // Get the updated branch information.
                 branch = repo.Branches[testBranchName];
@@ -548,15 +560,16 @@ public void CanSetLocalUpstreamBranch()
 
                 // Verify the IsTracking and TrackedBranch properties.
                 Assert.True(branch.IsTracking);
-                Assert.Equal(upstreamBranch, branch.TrackedBranch);
+                Assert.Equal(trackedBranch, branch.TrackedBranch);
+                Assert.Equal("refs/heads/master", branch.UpstreamBranchCanonicalName);
             }
         }
 
         [Fact]
-        public void CanUnsetUpstreamBranch()
+        public void CanUnsetTrackedBranch()
         {
             const string testBranchName = "branchToSetUpstreamInfoFor";
-            const string upstreamBranchName = "refs/remotes/origin/master";
+            const string trackedBranchName = "refs/remotes/origin/master";
 
             string path = CloneStandardTestRepo();
             using (var repo = new Repository(path))
@@ -565,16 +578,18 @@ public void CanUnsetUpstreamBranch()
                 Assert.False(branch.IsTracking);
 
                 branch = repo.Branches.Update(branch,
-                    b => b.Upstream = upstreamBranchName);
+                    b => b.TrackedBranch = trackedBranchName);
 
                 // Got the updated branch from the Update() method
                 Assert.True(branch.IsTracking);
 
                 branch = repo.Branches.Update(branch,
-                    b => b.Upstream = null);
+                    b => b.TrackedBranch = null);
 
                 // Verify this is no longer a tracking branch
                 Assert.False(branch.IsTracking);
+                Assert.Null(branch.Remote);
+                Assert.Null(branch.UpstreamBranchCanonicalName);
             }
         }
 

LibGit2Sharp/Branch.cs

@@ -129,6 +129,26 @@ public virtual ICommitLog Commits
             get { return repo.Commits.QueryBy(new Filter { Since = this }); }
         }
 
+        /// <summary>
+        ///   Gets the configured canonical name of the upstream branch.
+        ///   <para>
+        ///     This is the upstream reference to which this branch will be pushed.
+        ///     It corresponds to the "branch.branch_name.merge" property of the config file.
+        ///   </para>
+        /// </summary>
+        public virtual string UpstreamBranchCanonicalName
+        {
+            get
+            {
+                if (IsRemote)
+                {
+                    return Remote.FetchSpecTransformToSource(CanonicalName);
+                }
+
+                return UpstreamBranchCanonicalNameFromLocalBranch();
+            }
+        }
+
         /// <summary>
         ///   Gets the configured <see cref="Remote"/> to fetch from and push to.
         /// </summary>
@@ -156,6 +176,18 @@ public virtual Remote Remote
             }
         }
 
+        private string UpstreamBranchCanonicalNameFromLocalBranch()
+        {
+            ConfigurationEntry<string> mergeRefEntry = repo.Config.Get<string>("branch", Name, "merge");
+
+            if (mergeRefEntry == null)
+            {
+                return null;
+            }
+
+            return mergeRefEntry.Value;
+        }
+
         private string RemoteNameFromLocalBranch()
         {
             ConfigurationEntry<string> remoteEntry = repo.Config.Get<string>("branch", Name, "remote");

LibGit2Sharp/BranchUpdater.cs

@@ -41,7 +41,26 @@ internal BranchUpdater(Repository repo, Branch branch)
         ///   master branch.
         ///   </para>
         /// </summary>
+        [Obsolete("This property will be removed in the next release. Please use BranchUpdate.TrackedBranch instead.")]
         public virtual string Upstream
+        {
+            set { TrackedBranch = value; }
+        }
+
+        /// <summary>
+        ///   Sets the upstream information for the branch.
+        ///   <para>
+        ///     Passing null or string.Empty will unset the upstream.
+        ///   </para>
+        ///   <para>
+        ///     The upstream branch name is with respect to the current repository.
+        ///     So, passing "refs/remotes/origin/master" will set the current branch
+        ///     to track "refs/heads/master" on the origin. Passing in
+        ///     "refs/heads/master" will result in the branch tracking the local
+        ///     master branch.
+        ///   </para>
+        /// </summary>
+        public virtual string TrackedBranch
         {
             set
             {
@@ -58,28 +77,56 @@ public virtual string Upstream
         /// <summary>
         ///   Set the upstream merge branch directly for this branch.
         ///   <para>
-        ///   To track the "master" branch on the "origin" remote, set the
-        ///   UpstreamRemote property to "origin" and the UpstreamMergeBranch
-        ///   property to "refs/heads/master".
-        /// </para>
+        ///     To track the "master" branch on the "origin" remote, set the
+        ///     <see cref="Remote"/> property to "origin" and the <see cref="UpstreamBranch"/>
+        ///     property to "refs/heads/master".
+        ///   </para>
         /// </summary>
+        [Obsolete("This property will be removed in the next release. Please use BranchUpdate.UpstreamBranch instead.")]
         public virtual string UpstreamMergeBranch
+        {
+            set { UpstreamBranch = value; }
+        }
+
+        /// <summary>
+        ///   Set the upstream branch for this branch.
+        ///   <para>
+        ///     To track the "master" branch on the "origin" remote, set the
+        ///     <see cref="Remote"/> property to "origin" and the <see cref="UpstreamBranch"/>
+        ///     property to "refs/heads/master".
+        ///   </para>
+        /// </summary>
+        public virtual string UpstreamBranch
         {
             set
             {
-                SetUpstreamMergeBranch(value);
+                SetUpstreamBranch(value);
             }
         }
 
         /// <summary>
-        ///   Set the upstream remote for this branch.
+        ///   Set the upstream merge branch directly for this branch.
         ///   <para>
         ///   To track the "master" branch on the "origin" remote, set the
-        ///   UpstreamRemote property to "origin" and the UpstreamMergeBranch
+        ///   RemoteName property to "origin" and the UpstreamMergeBranch
         ///   property to "refs/heads/master".
         /// </para>
         /// </summary>
+        [Obsolete("This property will be removed in the next release. Please use BranchUpdate.UpstreamMergeBranchCanonicalName instead.")]
         public virtual string UpstreamRemote
+        {
+            set { Remote = value; }
+        }
+
+        /// <summary>
+        ///   Set the upstream remote for this branch.
+        ///   <para>
+        ///     To track the "master" branch on the "origin" remote, set the
+        ///     <see cref="Remote"/> property to "origin" and the <see cref="UpstreamBranch"/>
+        ///     property to "refs/heads/master".
+        /// </para>
+        /// </summary>
+        public virtual string Remote
         {
             set
             {
@@ -90,7 +137,7 @@ public virtual string UpstreamRemote
         private void UnsetUpstream()
         {
             SetUpstreamRemote(string.Empty);
-            SetUpstreamMergeBranch(string.Empty);
+            SetUpstreamBranch(string.Empty);
         }
 
         /// <summary>
@@ -117,14 +164,14 @@ private void SetUpstream(string upstreamBranchName)
             GetUpstreamInformation(upstreamBranchName, out remoteName, out branchName);
 
             SetUpstreamRemote(remoteName);
-            SetUpstreamMergeBranch(branchName);
+            SetUpstreamBranch(branchName);
         }
 
         /// <summary>
         ///   Set the upstream merge branch for the local branch.
         /// </summary>
         /// <param name="mergeBranchName">The merge branch in the upstream remote's namespace.</param>
-        private void SetUpstreamMergeBranch(string mergeBranchName)
+        private void SetUpstreamBranch(string mergeBranchName)
         {
             string configKey = string.Format("branch.{0}.merge", branch.Name);
 
@@ -188,11 +235,7 @@ private void GetUpstreamInformation(string canonicalName, out string remoteName,
                 remoteName = Proxy.git_branch_remote_name(repo.Handle, canonicalName);
 
                 Remote remote = repo.Network.Remotes.RemoteForName(remoteName);
-                using (RemoteSafeHandle remoteHandle = Proxy.git_remote_load(repo.Handle, remote.Name, true))
-                {
-                    GitRefSpecHandle refSpecPtr = Proxy.git_remote_fetchspec(remoteHandle);
-                    mergeBranchName = Proxy.git_refspec_rtransform(refSpecPtr, canonicalName);
-                }
+                mergeBranchName = remote.FetchSpecTransformToSource(canonicalName);
             }
             else
             {

LibGit2Sharp/Remote.cs

@@ -73,6 +73,20 @@ public virtual void Fetch(
             repository.Network.Fetch(this, tagFetchMode, onProgress, onCompletion, onUpdateTips, onTransferProgress, credentials);
         }
 
+        /// <summary>
+        ///   Transform a reference to its source reference using the <see cref = "Remote" />'s default fetchspec.
+        /// </summary>
+        /// <param name="reference">The reference to transform.</param>
+        /// <returns>The transformed reference.</returns>
+        internal string FetchSpecTransformToSource(string reference)
+        {
+            using (RemoteSafeHandle remoteHandle = Proxy.git_remote_load(repository.Handle, Name, true))
+            {
+                GitRefSpecHandle fetchSpecPtr = Proxy.git_remote_fetchspec(remoteHandle);
+                return Proxy.git_refspec_rtransform(fetchSpecPtr, reference);
+            }
+        }
+
         /// <summary>
         ///   Determines whether the specified <see cref = "Object" /> is equal to the current <see cref = "Remote" />.
         /// </summary>