git push --set-upstream vs --set-upstream-to

Question

according to this article, git push --set-upstream is deprecated and git push --set-upstream-to should be used instead.

But when I checked the git push documentation, I can only find --set-upstream, but --set-upstream-to is no where to be found.

So is --set-upstream deprecated? Should I use --set-upstream or --set-upstream-to?

Answer 1

This mixes up git branch and git push.

The git branch command has both --set-upstream and --set-upstream-to, with the former deprecated in favor of the latter for the reason already given in Nick's answer.

The git push command has only -u aka --set-upstream, which takes no argument. It means that if the push succeeds, your local Git should set, as the upstream of a branch reference supplied as your source, the remote-tracking branch corresponding to the destination branch you got the other Git to set, which in many cases, your own Git has just now created in your repository because their Git has also just created their branch. (Whew!)

That is, suppose you have created a branch newbranch:

$ git checkout -b newbranch
... work, commit, etc

and want to set its upstream to origin/newbranch. But if you try, it fails:

$ git branch --set-upstream-to=origin/newbranch
error: the requested upstream branch 'origin/newbranch' does not exist

because origin/newbranch does not exist yet, because the other git at origin does not have a branch named newbranch.

Soon, however, you git push your local newbranch to their Git, so that their Git creates newbranch in their repository. Now that they do have a newbranch, your Git creates your origin/newbranch to remember their newbranch. And now you can use git branch --set-upstream-to, but it might be nice if git push could do that automatically—and that's the git push --set-upstream, aka -u, option.

It's related to git branch --set-upstream-to, but not the same.