The upstream branch

A local branch can track one remote branch: its upstream. That is the branch the ahead and behind counts are measured against, and the one pull brings in. A branch with no upstream has no counts, and the pull and push badges stay empty on it.

Most of the time you never set one. Pushing a branch for the first time establishes it, switching to a remote branch creates a local one that tracks it, and GitFlow’s Publish pushes with tracking. The cases where you do are the ones where the name and the remote branch have come apart:

• a branch you created locally that should be measured against a remote branch which already exists;
• a branch whose remote counterpart lives on a second remote, or was renamed on the server;
• a branch you restored from Recovery, which comes back without the upstream it had;
• a branch whose upstream has been deleted on the server, and now counts against nothing.

Where it is

Right-click a local branch in the sidebar. Upstream Branch is a submenu of its context menu, there whenever the repository has a remote or the branch already tracks something, and absent on the rows under a remote — a remote branch is something to track, not something that tracks.

The submenu lists the remote branches that share the local branch’s name, one for each remote that has one, in the order of the remotes’ names. The one the branch tracks now is ticked and greyed out; choosing another sets it, and that is the whole operation.

Then, for everything the list does not cover:

• Choose Other… opens a chooser with every remote branch in it, for when the one you want has another name. It reads Choose Upstream… when no remote branch shares the local name, since the chooser is then the only way to pick one — and it is not there at all when the submenu has already listed every remote branch there is.
• Fetch Remotes takes the place of both when the repository has remotes but no remote branches have been fetched from them yet: there is nothing to choose until a fetch has been made.
• Remove Upstream, at the bottom, whenever the branch tracks something.

If the branch already tracks something the same-name list would not show, it appears ticked at the top of the submenu: a remote branch with a different name; another local branch, shown as main (local), which is a configuration Innesta will not make but will show you if something else made it; or a branch that no longer exists, shown as origin/old-name (unavailable), which is what an upstream deleted on the server and pruned by a fetch turns into. Remove Upstream works on all three.

The chooser

Choose Upstream Branch is a sheet: a search field over the remote branches, grouped by remote with a count on each group, with main, master and the branches GitFlow is configured on listed first. The branch the local one tracks now is ticked and cannot be chosen again.

Typing in Search remote branches narrows the list, matching anywhere in the full name and ignoring case. Up and down move the selection, Return is Set Upstream, and Escape is Cancel.

Opening the sheet does not fetch. It shows the remote branches Innesta already knows about, and Fetch Remotes in its header is how you ask for newer ones: the button reads Fetching… while the fetch runs, the groups refresh in place, and a selection that still exists afterwards is kept.

What it changes, and what it does not

Setting or removing an upstream changes the branch’s tracking configuration and nothing else. Nothing is checked out, fetched, pushed or committed; the working copy is not touched; no branch on the remote is created or deleted; the branch you are on and the commit you are looking at stay where they are. The counts on the branch’s row refresh at once, and the status bar says what happened — Upstream set to origin/main, or Upstream removed from feature/scanner.

After removing it

The branch keeps its commits and its name; it simply counts against nothing and pulls from nothing. The next push of it publishes the branch and gives it an upstream again.