1

It seems to me that the phrase 'upstream branch' is ambiguous and appears to have two contexts.

  1. an upstream branch is one that is tracked by a local branch (see Git Branching - Remote Branches), and

  2. an upstream branch is something in the context of rebasing (see Git Branching - Rebasing).

'upstream' in (2) is displayed in the CLI help:

$ git rebase -h
usage: git rebase [-i] [options] [--exec <cmd>] [--onto <newbase>] [<upstream>] [<branch>]
   or: git rebase [-i] [options] [--exec <cmd>] [--onto <newbase>] --root [<branch>]
   or: git-rebase --continue | --abort | --skip | --edit-todo

The first one is clear to me but, for the life of me, I can't seem to wrap my head around what 'upstream' refers to in rebase. Furthermore, I've come across having 'multiple upstream branches', (git branch with multiple upstreams) which further confounds this conundrum.

It seems to me that this notion of 'upstream branch' needs some disambiguation in the git-scm.com documentation. This would go a long way towards making sense of such commands as:

$ git rebase --onto master server client

described in Git Branching - Rebasing, and

$ git rebase master server
jonrsharpe
  • 115,751
  • 26
  • 228
  • 437
polarise
  • 2,303
  • 1
  • 19
  • 28
  • The branching and rebasing page you've linked doesn't appear to refer to "upstream". – jonrsharpe Oct 08 '20 at 12:58
  • Edited to show where it crops up. – polarise Oct 08 '20 at 13:01
  • They have the *same meaning*, the `` is the corresponding remote branch in both cases. – jonrsharpe Oct 08 '20 at 13:06
  • 1
    That's not clear. If I branched on local clearly the original branch is not _remote_. This is the confusion. Why not use a term like _original_? Please view the documentation. – polarise Oct 08 '20 at 13:08
  • 1
    I'm not a big fan of the terminology in the `git rebase` documentation, in part for the reason that you find here: calling one argument *`upstream`* just seems misleading. It *does* make sense, as in [isherwood's answer](https://stackoverflow.com/a/64263243/1256452), but in the synopsis I think some other term might be better. I have not yet hit on what i think is the *right* term: when using `--onto`, the right term might be `stop` or `limiter` or something, but without `--onto`, the argument currently called *`upstream`* acts as both the onto *and* the limiter. – torek Oct 09 '20 at 00:17

1 Answers1

2

Rebasing applies the commits made to a working branch to a branch that is or was an ancestor of that branch. If you think about the flow of an actual stream, an upstream branch is one that departed the current branch somewhere in the past.

Rebasing probably cannot apply to downstream branches, or those that have commits ahead of the current branch. For example, if you were to branch after doing some work, then check out the previous branch and attempt to rebase onto the second branch it wouldn't work.

So upstream really just refers to a branch that's part of the history of the current branch, and more specifically the branch onto which you intend to rebase. Local and remote are irrelevant.

isherwood
  • 58,414
  • 16
  • 114
  • 157