[git] 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.

This question is related to git push git-push git-remote upstream-branch

The answer is


git branch --set-upstream <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 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.


To avoid confusion, recent versions of git deprecate this somewhat ambiguous --set-upstream option in favour of a more verbose --set-upstream-to option with identical syntax and behaviour

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

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.


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


Examples related to git

Does the target directory for a git clone have to match the repo name? Git fatal: protocol 'https' is not supported Git is not working after macOS Update (xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools) git clone: Authentication failed for <URL> destination path already exists and is not an empty directory SSL_connect: SSL_ERROR_SYSCALL in connection to github.com:443 GitLab remote: HTTP Basic: Access denied and fatal Authentication How can I switch to another branch in git? VS 2017 Git Local Commit DB.lock error on every commit How to remove an unpushed outgoing commit in Visual Studio?

Examples related to push

Best way to "push" into C# array Firebase: how to generate a unique numeric ID for key? Why does Git tell me "No such remote 'origin'" when I try to push to origin? Unknown SSL protocol error in connection Git push rejected "non-fast-forward" How to add multiple files to Git at the same time git push to specific branch Declare an empty two-dimensional array in Javascript? What does '--set-upstream' do? fatal: 'origin' does not appear to be a git repository

Examples related to git-push

Fix GitLab error: "you are not allowed to push code to protected branches on this project"? ! [rejected] master -> master (fetch first) Git - What is the difference between push.default "matching" and "simple" error: src refspec master does not match any Issue pushing new code in Github Can't push to GitHub because of large file which I already deleted Changing the Git remote 'push to' default What does '--set-upstream' do? Git push hangs when pushing to Github? fatal: 'origin' does not appear to be a git repository

Examples related to git-remote

Why does Git tell me "No such remote 'origin'" when I try to push to origin? Git - What is the difference between push.default "matching" and "simple" error: src refspec master does not match any How to connect to a remote Git repository? Changing the Git remote 'push to' default What does '--set-upstream' do? Git: How to remove remote origin from Git repo Git push error: "origin does not appear to be a git repository" How to add a local repo and treat it as a remote repo Git branching: master vs. origin/master vs. remotes/origin/master

Examples related to upstream-branch

What does '--set-upstream' do?