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.
Suggested further reading:
But watch out for git quirks:
If <repository> is given as an URL or file path, see for example this example:
git push --set-upstream git@gitlab.example.com:namespace/myproject.git master
git push
does not create a reference to the remote branch head in .git/refs/remotes/<repository>
Only if the upstream repository has been given a name using
git remote add <repository> <URL>
and git push --set-upstream
has been used with this name, the full power of remote tracking branches is available in all git commands.
Suggested further reading:
FYI: all commands tested with git V2.32 on Windows.