1

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:

Man page synopsis for git rebase

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?

Community
  • 1
  • 1
makansij
  • 9,303
  • 37
  • 105
  • 183
  • 7
    `<>` does *not* mean mandatory parameter. Lack of brackets `[]` means that. `<>` just means "don't literally put the string that's inside of these, but substitute a value that makes sense in context". – Chris Hayes Sep 13 '15 at 03:13
  • 3
    `` does *not* mean "mandatory parameter". That simply means it's not a literal value -- that is, it's something for which you substitute a real value, like a branch name. Mandatory parameters are not listed inside `[...]`. – larsks Sep 13 '15 at 03:13
  • hmmmm [this](http://www.tfug.org/helpdesk/general/man.html) source indicates that mandatory parameters are in ` <>`. But, what you say makes more sense, given the context. I assume that source is wrong? – makansij Sep 13 '15 at 03:18
  • "Blob" is the wrong term to use. I think you meant to say "ref"? – Nayuki Sep 13 '15 at 03:37
  • I thought that a "ref" was a type of ["blob"](http://www.gitguys.com/topics/the-git-object-model-starting-with-the-blob/), or am I further exposing my ignorance? – makansij Sep 13 '15 at 03:54

1 Answers1

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".

Community
  • 1
  • 1
VonC
  • 1,262,500
  • 529
  • 4,410
  • 5,250
  • This is awesome. Okay so, "`branch..remote` and `branch..merge` options will be used" - I saw this in the man page too. But, I checked out `git-config(1)`, like it says to, and I couldn't find anything on it. I also couldn't find it in the `config` file in the directory `.git`. Hints on where to find that? – makansij Sep 13 '15 at 04:36
  • 1
    @Hunle If you cannot find the config in the .git, it simply means there is no local config yet for that repo. Those two configs are set when a local branch has an upstream branch. See http://git-scm.com/docs/git-branch: "When a local branch is started off a remote-tracking branch, Git sets up the branch (specifically the `branch..remote` and `branch..merge` configuration entries) so that `git pull` will appropriately merge from the remote-tracking branch." – VonC Sep 13 '15 at 04:47
  • I guess part of my confusion here stems from the fact that `HEAD` seems to be able to refer to both a `commit`, and a `branch`. It seems to point to a `commit` first, and then, if required, can provide the branch upon which that commit resides. Is that true? – makansij Sep 13 '15 at 18:22
  • @Hunle HEAD is "current commit" everywhere in git. See my old answer http://stackoverflow.com/a/964927/6309, and the one above that old answer. – VonC Sep 13 '15 at 18:23