What does it mean to specify two blobs in `git rebase`?

Question

My question is in two parts.

First part: Two blobs in git rebase

I am familiar with git rebase -i HEAD^n, where n means the number of commits ago you wish to rebase onto.

But, I also sometimes see git rebase -i <branch> HEAD. In that case - How does the added <branch> parameter make a difference?

Second part: man page for git rebase

So....I checked the man page, and I see the following:

On that man page, I see [<upstream> [<branch>]], which I think might answer my question to the first part.

But, the peculiar thing about this is that I know <> means mandatory parameter, and [] means optional parameter. In [<upstream> [<branch>]], I see a mandatory parameter inside of an optional parameter. What does this mean?

Answer 1

How does the added <branch> parameter make a difference?

It does because a rebase replays all commits between upstream and branch.

• git rebase -i HEAD^n means all commits between HEAD^n and the current branch HEAD
• git rebase -i <branch> HEAD (or git rebase -i <branch>) means all commits between <branch> HEAD (which is here the upstream branch) and the current branch HEAD. For example: git rebase -i origin/master HEAD: all commits not yet pushed.

[<upstream> [<branch>]] means both parameters are optional.
Since git has been created by the author of Linux, see man-pages - conventions for writing Linux man pages

Brackets ([]) surround optional arguments

For git rebase, those optional parameters are:

If <branch> is specified, git rebase will perform an automatic git checkout <branch> before doing anything else. Otherwise it remains on the current branch.

If <upstream> is not specified, the upstream configured in branch.<name>.remote and branch.<name>.merge options will be used.
The current branch is reset to <upstream>. This has the exact same effect as git reset --hard <upstream>.

Regarding <...> convention, see for instance "Utility Argument Syntax":

names of parameters that require substitution by actual values are shown as follow:

<parameter name>

The angle brackets are used for the symbolic grouping of a phrase representing a single parameter and conforming applications shall not include them in data submitted to the utility.

Finally, a ref is not a type of blob.
A ref is (see "Git Internals - Git References") a reference to a SHA1 value.
A blob represents a content stored in a git repo. See "Git Internals - Git Objects - Object storage".