What does '--set-upstream' do?

What does git --set-upstream do?

I tried to understand it by reading the git manual, but I didn't quite get it.

Solution 1:

To avoid confusion,
recent versions of git deprecate this somewhat ambiguous --set-upstream option
in favor of a more verbose --set-upstream-to option
with identical syntax and behavior.
[ Reference ]

git branch --set-upstream-to <remote-branch>

sets the default remote branch for the current local branch.

Any future git pull command (with the current local branch checked-out),
will attempt to bring in commits from the <remote-branch> into the current local branch.

One way to avoid having to explicitly type --set-upstream / --set-upstream-to is to use its shorthand flag -u as follows:

git push -u origin local-branch

This sets the upstream association for any future push/pull attempts automatically.
For more details, checkout this detailed explanation about upstream branches and tracking.

Solution 2:

When you push to a remote and you use the --set-upstream flag git sets the branch you are pushing to as the remote tracking branch of the branch you are pushing.

Adding a remote tracking branch means that git then knows what you want to do when you git fetch, git pull or git push in future. It assumes that you want to keep the local branch and the remote branch it is tracking in sync and does the appropriate thing to achieve this.

You could achieve the same thing with git branch --set-upstream-to or git checkout --track. See the git help pages on tracking branches for more information.

Solution 3:

git branch --set-upstream <<origin/branch>> is officially not supported anymore and is replaced by git branch --set-upstream-to <<origin/branch>>

Solution 4:

I'm assuming that your question is:

What does git push --set-upstream <repository> <branchname> do?

As you see, I assumed that the git command in question is git push. I hope that is what you meant. For simplifying the answer, I further specified that the local branch <branchname> that you are on has the same name as the remote branch on your upstream repository <repository> that you are pushing to. Finally, I assume a common git configuration.

With that said, this is my answer:

In addition to the operation that a git push without the option --set-upstream does, this option makes git push set at least two configuration variables:

branch.<branchname>.remote = <repository>
branch.<branchname>.merge = /ref/heads/<branchname>

That's all this command does. It stores upstream information (i.e., remote repository and branch) for the local branch in config variables.

Upstream information is stored under the local branch name. If your local branch is called main, the respective config variables are branch.main.remote and branch.main.merge. Based on the way how this upstream information is stored, a local branch can have no more than a single set of upstream information.

You can query whether any of these config variables are set using git config --get-regexp ^branch\.. This will output any variables that start with "branch."

The magic happens when these config variables are used by, e.g., git fetch, git pull or git push to figure out the upstream repository and remote branch for a local branch if you don't explicitly specify them on the commandline. That is, when these config variables are set, you can just issue git push and git will know (using these variables) the remote repository and upstream branch to use.

Solution 5:

--set-upstream is used to map a branch in your local to a branch on remote so that you can just do git push or git pull and it will know which branch to push/pull from

For adding a remote repo I use these commands

First, check your remote repositories with git remote -v
If you can't see upstream then use git remote add upstream <URL>
Check again your remote repositories with git remote -v

One can have multiple remote's to their local repository and it can be added using the same commands above.

Just change the upstream name git remote add NAME <URL>