feat(git): mark the last pushed commit in history

The history table listed every commit alike, so nothing said which of them
the remote already has, or whether the branch had ever been pushed at all.

Draw a waterline where the remote's branch points. Commits above it carry
the same orange left edge the gutter puts on a modified line, so "edge
means not saved upstream yet" reads the same in the editor and here. The
marker takes its colour from the state it describes: blue while there is
nothing to push, orange once commits are waiting, so the run of orange
above closes on an orange line and reads as one mark. A branch with no
counterpart on the remote gets a "not pushed" banner instead, closed off
at the initial commit once the whole history is on screen.

Where the remote points comes from one `for-each-ref` reading the branch
and the remote ref together — the branch row carries the upstream's name,
the remote row the hash. A branch tracking some other ref needs a second
call; nothing else does, and paging costs none, since the answer latches
once the waterline is placed.

File history is left alone: it lists only the commits touching one file,
so the remote's head is usually not among them and every row would be
wrongly called local.

Author: abose

src/extensions/default/Git/src/History.js

@@ -6,6 +6,7 @@ define(function (require) {
         FileUtils = brackets.getModule("file/FileUtils"),
         LocalizationUtils = brackets.getModule("utils/LocalizationUtils"),
         Strings = brackets.getModule("strings"),
+        StringUtils = brackets.getModule("utils/StringUtils"),
         Metrics = brackets.getModule("utils/Metrics"),
         NotificationUI = brackets.getModule("widgets/NotificationUI"),
         Mustache = brackets.getModule("thirdparty/mustache/mustache");
@@ -20,7 +21,8 @@ define(function (require) {
 
     // Templates
     var gitPanelHistoryTemplate = require("text!templates/git-panel-history.html"),
-        gitPanelHistoryCommitsTemplate = require("text!templates/git-panel-history-commits.html");
+        gitPanelHistoryCommitsTemplate = require("text!templates/git-panel-history-commits.html"),
+        gitPanelHistoryEndTemplate = require("text!templates/git-panel-history-end.html");
 
     // Module variables
     let $gitPanel         = $(null),
@@ -29,6 +31,14 @@ define(function (require) {
         commitCache       = [],
         lastDocumentSeen  = null;
 
+    // Where the branch stands against its remote, for the push waterline.
+    // `remoteHead` is null when the branch has no counterpart on the remote at
+    // all; `remoteHeadSeen` latches once the waterline has been placed, so the
+    // pages loaded after it are known to be pushed without re-testing them.
+    let remoteHead      = null,
+        remoteHeadSeen  = false,
+        unpushedCount   = 0;
+
     // must match the page size git log is invoked with in GitCli.getHistory
     const HISTORY_PAGE_SIZE = 100;
 
@@ -100,12 +110,15 @@ define(function (require) {
     function _renderHistoryTable(commits, file) {
         // calculate some missing stuff like avatars
         commits = addAdditionalCommitInfo(commits);
+        commits = markPushState(commits, file);
         commitCache = commitCache.concat(commits);
 
         const templateData = {
             commits: commits,
-            emptyMessage: file ? Strings.GIT_FILE_HISTORY_NOTHING_TO_SHOW : Strings.GIT_HISTORY_NOTHING_TO_SHOW,
-            Strings: Strings
+            // the banner only makes sense for a branch, not one file's history
+            notPushed: !file && !remoteHead && commits.length > 0,
+            Strings: Strings,
+            emptyMessage: file ? Strings.GIT_FILE_HISTORY_NOTHING_TO_SHOW : Strings.GIT_HISTORY_NOTHING_TO_SHOW
         };
 
         $tableContainer.find("#git-history-list").remove();
@@ -120,10 +133,30 @@ define(function (require) {
         if (commits.length < HISTORY_PAGE_SIZE) {
             // the full history is already here, so the last commit is the initial
             // one. with more pages the initial commit is marked by loadMoreHistory.
-            $historyList.attr("x-finished", "true");
-            $historyList
-                .find("tr.history-commit:last-child")
-                .attr("x-initial-commit", "true");
+            markHistoryFinished();
+        }
+    }
+
+    /**
+     * Note that the whole history is on screen.
+     *
+     * Marks the oldest commit so HistoryViewer knows it has nothing to diff
+     * against, and, for a branch with no counterpart on the remote, closes the
+     * unpushed run with a line — only here, because until the initial commit is
+     * reached a closing line would claim a bottom the list does not have yet.
+     *
+     * Matches the last commit row with `.last()` rather than `:last-child`: the
+     * waterline rows are siblings, so the oldest commit is not always the final
+     * child of the table body.
+     */
+    function markHistoryFinished() {
+        $historyList.attr("x-finished", "true");
+        const $lastCommit = $historyList.find("tr.history-commit").last();
+        $lastCommit.attr("x-initial-commit", "true");
+        if (!remoteHead && $lastCommit.length && !$historyList.find("tr.history-push-end").length) {
+            $lastCommit.after(Mustache.render(gitPanelHistoryEndTemplate, {
+                allLocalText: StringUtils.format(Strings.GIT_HISTORY_ALL_LOCAL, unpushedCount)
+            }));
         }
     }
 
@@ -134,14 +167,25 @@ define(function (require) {
         // clear cache
         commitCache = [];
 
+        // the waterline is recomputed per render: the remote may have moved
+        remoteHead = null;
+        remoteHeadSeen = false;
+        unpushedCount = 0;
+
         return Git.getCurrentBranchName().then(function (branchName) {
-            // Get the history commits of the current branch
-            var p = file ? Git.getFileHistory(file.relative, branchName) : Git.getHistory(branchName);
-            return p.then(function (commits) {
-                if (renderId === historyRenderId) {
-                    _renderHistoryTable(commits, file);
-                }
-                return true;
+            return Git.getRemoteBranchHead(branchName).catch(function () {
+                // a repo without remotes is normal, not an error to surface
+                return null;
+            }).then(function (head) {
+                remoteHead = head;
+                // Get the history commits of the current branch
+                var p = file ? Git.getFileHistory(file.relative, branchName) : Git.getHistory(branchName);
+                return p.then(function (commits) {
+                    if (renderId === historyRenderId) {
+                        _renderHistoryTable(commits, file);
+                    }
+                    return true;
+                });
             });
         }).catch(function (err) {
             if (renderId !== historyRenderId) {
@@ -184,15 +228,13 @@ define(function (require) {
                             return;
                         }
                         if (commits.length === 0) {
-                            $historyList.attr("x-finished", "true");
                             // marks initial commit as first
-                            $historyList
-                                .find("tr.history-commit:last-child")
-                                .attr("x-initial-commit", "true");
+                            markHistoryFinished();
                             return;
                         }
 
                         commits = addAdditionalCommitInfo(commits);
+                        commits = markPushState(commits, file);
                         commitCache = commitCache.concat(commits);
 
                         var templateData = {
@@ -241,6 +283,55 @@ define(function (require) {
         return commits;
     }
 
+    /**
+     * Flag each commit against the remote, for the waterline the table draws.
+     *
+     * Commits arrive newest first, so everything listed before the remote's
+     * head is still local: walk until that commit shows up, mark it, and leave
+     * the rest alone — they are older than the remote tip and therefore pushed.
+     * The latch carries the answer across pages, since every later page is
+     * older than the one before it. With no counterpart on the remote nothing
+     * has been pushed and every commit is flagged.
+     *
+     * File history is skipped entirely: it lists only the commits touching one
+     * file, so the remote's head usually is not among them and every row would
+     * be wrongly called local.
+     *
+     * @param {Array<Object>} commits - commits for this page, newest first
+     * @param {?(Object|string)} file - whatever the caller holds for the file on
+     *      show; only its presence matters, the first page has the object and
+     *      later pages the relative path
+     * @return {Array<Object>} the same commits, flagged in place
+     */
+    function markPushState(commits, file) {
+        if (file) {
+            return commits;
+        }
+        _.forEach(commits, function (commit) {
+            if (!remoteHead) {
+                commit.unpushed = true;
+                return;
+            }
+            if (remoteHeadSeen) {
+                return;
+            }
+            if (commit.hash === remoteHead.hash) {
+                commit.isRemoteHead = true;
+                // the ref name is a git identifier, never translated
+                commit.remoteRef = remoteHead.ref;
+                commit.isAhead = unpushedCount > 0;
+                commit.pushStateText = commit.isAhead
+                    ? StringUtils.format(Strings.GIT_HISTORY_AHEAD, unpushedCount)
+                    : Strings.GIT_HISTORY_UP_TO_DATE;
+                remoteHeadSeen = true;
+                return;
+            }
+            commit.unpushed = true;
+            unpushedCount++;
+        });
+        return commits;
+    }
+
     function getCurrentDocument() {
         if (HistoryViewer.isVisible()) {
             return lastDocumentSeen;

src/extensions/default/Git/src/git/Git.js

@@ -82,6 +82,10 @@ define(function (require, exports) {
         return GitCli.getHistory(branch, skip, file);
     }
 
+    function getRemoteBranchHead(branch) {
+        return GitCli.getRemoteBranchHead(branch);
+    }
+
     function resetIndex() {
         return GitCli.reset();
     }
@@ -180,6 +184,7 @@ define(function (require, exports) {
     exports.getAllBranches          = getAllBranches;
     exports.getHistory              = getHistory;
     exports.getFileHistory          = getFileHistory;
+    exports.getRemoteBranchHead     = getRemoteBranchHead;
     exports.resetIndex              = resetIndex;
     exports.discardAllChanges       = discardAllChanges;
     exports.getMergeInfo            = getMergeInfo;

src/extensions/default/Git/src/git/GitCli.js

@@ -501,6 +501,76 @@ define(function (require, exports) {
             });
     }
 
+    /**
+     * Where the current branch's counterpart on the remote points right now.
+     *
+     * The configured upstream wins, but a branch pushed with an explicit refspec
+     * often never gets one, so the default remote's branch of the same name
+     * stands in — otherwise history would call a pushed branch local. Resolves
+     * to null when neither ref is there, which is what a branch that has never
+     * been pushed looks like.
+     *
+     * Usually one git call: a single `for-each-ref` reads the branch and that
+     * default-remote ref together, giving the upstream's name and the hash in
+     * the same pass. Only a branch tracking some other ref needs a second.
+     *
+     * @param {string} branch - name of the current branch
+     * @return {Promise<?{ref: string, hash: string}>} null when there is no counterpart
+     */
+    function getRemoteBranchHead(branch) {
+        if (!branch) {
+            return Promise.resolve(null);
+        }
+        const remotes = Preferences.get("defaultRemotes") || {};
+        const remote = remotes[Preferences.get("currentGitRoot")];
+        const guess = remote ? remote + "/" + branch : null;
+        // The full refname disambiguates: a branch really can be called
+        // "origin/ai", and then both rows would answer to the same short name.
+        const localRef = "refs/heads/" + branch;
+        const guessRef = guess ? "refs/remotes/" + guess : null;
+        // "|" is legal in a ref name, so the fields are parted the way
+        // getHistory above does it rather than on a character refs may contain.
+        const separator = "_._";
+        const args = [
+            "for-each-ref",
+            "--format=%(refname)" + separator + "%(upstream:short)" + separator + "%(objectname)",
+            localRef
+        ];
+        if (guessRef) { args.push(guessRef); }
+
+        // One pass over both refs: the branch row carries the upstream's name,
+        // the remote row carries the hash. A ref that is not there prints
+        // nothing rather than failing, so absence needs no special case.
+        return git(args).then(function (stdout) {
+            let upstream = null, guessHash = null;
+            (stdout || "").split("\n").forEach(function (line) {
+                const parts = line.trim().split(separator);
+                if (parts.length < 3) { return; }
+                if (parts[0] === localRef) {
+                    upstream = parts[1] || null;
+                } else if (parts[0] === guessRef) {
+                    guessHash = parts[2] || null;
+                }
+            });
+            if (upstream && upstream !== guess) {
+                // Tracking something other than <remote>/<branch>, so its hash
+                // was not in the pass above. rev-parse resolves it whatever it
+                // is — a remote-tracking ref, or a local branch for `remote = .`
+                return git(["rev-parse", "--verify", "--quiet", upstream])
+                    .then(function (out) {
+                        const hash = (out || "").trim();
+                        return hash ? { ref: upstream, hash: hash } : null;
+                    })
+                    .catch(function () { return null; });
+            }
+            // The upstream is the ref just read, or there is no upstream and the
+            // branch was pushed to its own name; either way the hash is in hand.
+            return guessHash ? { ref: guess, hash: guessHash } : null;
+        }).catch(function () {
+            return null;
+        });
+    }
+
     // Get list of deleted files between two branches
     function getDeletedFiles(oldBranch, newBranch) {
         return git(["diff", "--no-ext-diff", "--name-status", oldBranch + ".." + newBranch])
@@ -1166,6 +1236,7 @@ define(function (require, exports) {
     exports.setUpstreamBranch         = setUpstreamBranch;
     exports.getCurrentBranchName      = getCurrentBranchName;
     exports.getCurrentUpstreamBranch  = getCurrentUpstreamBranch;
+    exports.getRemoteBranchHead       = getRemoteBranchHead;
     exports.getConfig                 = getConfig;
     exports.setConfig                 = setConfig;
     exports.getBranches               = getBranches;

src/extensions/default/Git/styles/git-styles.less

@@ -452,6 +452,95 @@
             width: 50px;
         }
     }
+    // The push waterline: commits above it are not on the remote yet. They
+    // carry the same orange edge the gutter puts on a modified line, so "edge
+    // means not saved upstream yet" reads the same in the editor and here.
+    // box-shadow rather than the gutter's border-left, which would widen the
+    // cell and shift the whole column.
+    tbody tr.history-commit.unpushed > td:first-child {
+        box-shadow: inset 3px 0 0 @git-orange;
+        .dark & {
+            box-shadow: inset 3px 0 0 @dark-git-orange;
+        }
+    }
+    tbody tr.history-push-line > td {
+        width: auto;
+        padding: 0;
+        border: 0;
+        background: none;
+        .push-line-inner {
+            display: flex;
+            align-items: center;
+            gap: 8px;
+            padding: 3px 10px 3px 8px;
+            user-select: none;
+        }
+        // Blue while there is nothing to push: the ref is just a landmark. The
+        // `.ahead` rule below repaints it when commits are waiting, so the
+        // marker states what is pending instead of always looking urgent.
+        .push-line-ref {
+            display: inline-flex;
+            align-items: center;
+            gap: 5px;
+            flex: 0 0 auto;
+            font-size: 10.5px;
+            line-height: 1;
+            font-weight: 600;
+            white-space: nowrap;
+            padding: 3px 7px;
+            border-radius: 3px;
+            color: @git-blue-text;
+            border: 1px solid @git-blue-text;
+            .dark & {
+                color: @git-dark-blue-text;
+                border-color: @git-dark-blue-text;
+            }
+        }
+        .push-line-rule {
+            flex: 1 1 auto;
+            height: 0;
+            border-top: 1px dashed @git-blue-text;
+            opacity: 0.45;
+            .dark & {
+                border-top-color: @git-dark-blue-text;
+            }
+        }
+        .push-line-note {
+            flex: 0 0 auto;
+            font-size: 10px;
+            white-space: nowrap;
+            opacity: 0.8;
+            color: @git-blue-text;
+            .dark & {
+                color: @git-dark-blue-text;
+            }
+        }
+    }
+    // Commits are waiting: the orange run above closes on an orange line, so
+    // the block and its boundary read as one mark rather than two.
+    tbody tr.history-push-line.ahead > td {
+        .push-line-ref {
+            color: @git-orange-text;
+            border-color: @git-orange;
+            .dark & {
+                color: @dark-git-orange;
+                border-color: @dark-git-orange;
+            }
+        }
+        .push-line-rule {
+            border-top-color: @git-orange;
+            opacity: 0.9;
+            .dark & {
+                border-top-color: @dark-git-orange;
+            }
+        }
+        .push-line-note {
+            color: @git-orange-text;
+            .dark & {
+                color: @dark-git-orange;
+            }
+        }
+    }
     tbody tr.history-empty-message td {
         width: auto;
         padding: 15px;