Home Software Engineering How To Set Upstream Branch on Git

How To Set Upstream Branch on Git

by schkn

When cloning a Git repository or creating new feature branches, you will have to set upstream branches in order to work properly.

But what are upstream branches?

Upstream branches are closely associated with remote branches.

Upstream branches define the branch tracked on the remote repository by your local remote branch (also called the remote tracking branch)

upstream branch explained

When creating a new branch, or when working with existing branches, it can be quite useful to know how you can set upstream branches on Git.

Set upstream branch using git push

The easiest way to set the upstream branch is to use the “git push” command with the “-u” option for upstream branch.

$ git push -u <remote> <branch>

Alternatively, you can use the “–set-upstream” option that is equivalent to the “-u” option.

$ git push --set-upstream <remote> <branch>

As an example, let’s say that you created a branch named “branch” using the checkout command.

$ git checkout -b branch
Switched to a new branch 'branch'

You can check tracking branches by running the “git branch” command with the “-vv” option.

$ git branch -vv
* branch  808b598 Initial commit
 master  808b598 [origin/master] Initial commit

As you can see, compared to master, the branch “branch” has no tracking branches yet (and no upstream branches as a consequence)

We can set the upstream branch using the “git push” command.

$ git push -u origin branch
Total 0 (delta 0), reused 0 (delta 0)
 * [new branch]      branch -> branch
Branch 'branch' set up to track remote branch 'branch' from 'origin'.

Let’s have a look at the tracking branches again with the branch command.

$ git branch -vv
* branch  808b598 [origin/branch] Initial commit                                                                                                                                                               master  808b598 [origin/master] Initial commit


We have successfully set the upstream branch for our newly created branch.

Set upstream branch using an alias

Another way to set the upstream branch is to define an alias for your “git push” command.

In fact, pushing to HEAD is equivalent to pushing to a remote branch having the same name as your current branch.

$ git push -u origin HEAD

In order to avoid having to define the upstream everytime you create a new branch, define an alias for the command we just wrote.

For aliases, you have two choices, you can either create a git alias or a bash alias.

Using a git alias

In order to create a new git alias, use the “git config” command and define a new alias named “pushd”

$ git config --global alias.pushd "push -u origin HEAD"

When you are done adding and committing fiels to your repository, set the upstream branch using your newly defined alias.

$ git pushd
Total 0 (delta 0), reused 0 (delta 0)
 * [new branch]      HEAD -> branch
Branch 'branch' set up to track remote branch 'branch' from 'origin'.

Using a bash alias

Alternatively, you can use a bash alias if you don’t want to modify your existing git commands.

Define a new bash alias using the “alias” command and define a name for it.

$ alias gp='git push -u origin HEAD'

Let’s create a new branch and use our alias in order to push our code and create the upstream branch easily.

$ git checkout -b branch2
Total 0 (delta 0), reused 0 (delta 0)
 * [new branch]      HEAD -> branch2
Branch 'branch2' set up to track remote branch 'branch2' from 'origin'.

Set upstream branch for an existing remote branch

In some cases, you may choose to link your local branches to existing remote branches that you just pulled or cloned from the main repository.

Let’s say for example that you pulled the “dev” branch located on the “origin” remote.

As a consequence, the tracking branch is named “origin/dev”.

Set tracking branches for new local branches

In order to switch to the local “dev” branch, and to set the “origin/dev” as the tracking branch (or upstream branch), use the “–track” option.

$ git checkout --track origin/dev

Branch 'dev' set up to track remote branch 'dev' from 'origin'.
Switched to a new branch 'dev'

To verify that you linked dev to the tracking branch “origin/dev” (which upstream branch is the remote dev), use the “git branch” command.

$ git branch -vv
* dev 808b598 [origin/dev] Initial commit

Set tracking branches for existing local branches

On the other hand, you may have chosen to work on a local branch and to set the upstream branch (or the remote tracking branch later on).

It is perfectly fine, but you will have to use the “git branch” in order to set the existing branch upstream branch.

$ git branch -u <remote>/<branch>

Let’s take the example of the “feature” branch that you just created to start working.

$ git checkout -b feature
Switched to a new branch 'feature'

You created some commits in your branch, you want to set the tracking branch to be master.

$ git branch -u origin/master
Branch 'feature' set up to track remote branch 'master' from 'origin'.

Great! You successfully set the upstream branch for your existing local branch.

Why are upstream branches so useful in Git?

Upstream branches are useful because :

  • You get references to your remote repositories and you essentially know if you are ahead of them or not.

When performing a “git fetch” command, you can bring the new commits from your remote repository and you can choose to merge them at will.

  • You can perform pull and push easily

When you set your upstream (or tracking) branches, you can simply execute pulls and pushes without having to specify the target branch.

Git automatically knows that it has to fetch the new commits to the remote tracking branch. Similarly, Git already knows that it has to push new commits to the upstream branch.

But where does Git keep a reference of the upstream branches associated with local branches?

Git keeps references to upstream branches via its config file in the “.git” directory.

Inspecting tracking branches configuration

In order to inspect your current Git configuration, list the hidden files and directories in your current working Git directory.

$ ls -al

total 16
drwxrwxr-x 3 schkn schkn 4096 Nov  5 16:10 .
drwxrwxr-x 7 schkn schkn 4096 Nov  5 16:10 ..
drwxrwxr-x 8 schkn schkn 4096 Nov  6 10:27 .git

Now, inspect the content of the “config” file located in the .git directory.

$ cat .git/config

        repositoryformatversion = 0
        filemode = true
        bare = false
        logallrefupdates = true
[remote "origin"]
        url = <repo_url>
        fetch = +refs/heads/*:refs/remotes/origin/*
[branch "master"]
        remote = origin
        merge = refs/heads/master

As you can see, Git keeps a reference between your local branch, the name of the remote and the branch it has to merge with.


In this tutorial, you learnt more about upstream branches and how they are related to remote tracking branches in Git.

You learnt different techniques in order to set remote tracking branches using a command or an alias to set it.

You also learnt how you can link your current local branches to existing remote tracking branches easily with the branch command.

If you are interested in Software Engineering, we have a complete section dedicated to it on the website so make sure to have a look.

You may also like


Links 2/11/2019: MidnightBSD 1.2, Python 3.5.9 | Techrights November 2, 2019 - 1:18 pm

[…] How To Set Upstream Branch on Git […]

Arjun November 7, 2019 - 11:01 pm

Very interesting article, thank you for helping me set the upstream branch

schkn November 7, 2019 - 11:02 pm

You are welcome!

Charles January 7, 2020 - 10:29 am

Hay man, Iam absolutely into the posts on your blog. They are made properly, easy to consume and remember, regardless of English being my 3rd language. Have you considered becoming writer?

How To Push Git Branch To Remote – devconnected February 15, 2020 - 9:24 am

[…] your upstream branch is not already created, you will need to create it by running the “git push” command […]

orochies June 26, 2020 - 6:37 pm

very useful article, thanks

Uchenna July 5, 2020 - 6:08 am

This is one of the best tutorial on setting up upstream that I have read. You took time to explain the concepts in details with perfect working examples. Thank you

schkn July 7, 2020 - 8:46 am

You’re welcome! Glad it helped.

Anand Kumar September 21, 2020 - 10:18 pm

It’s great
Very beautifully explained

schkn September 22, 2020 - 7:20 pm

Thank you!

Frank April 28, 2021 - 5:33 am

Thanks for being one of the few discussing upstream branches–even the GIT documentation doesn’t seem to cover it.

You have a subsection in your tutorial entitled “Why are upstream branches so useful in Git?” The advantages are obvious: basically, the branch works.

The real question for me is, “why is there even a technical possibility of not having an upstream branch?” Is there any point to a local branch that the repository doesn’t have? If creating a branch automatically created the remote branch too, and handled internally to GIT, and invisible to the user, such that we not even need think about upstream branches or have a word for this thing, what would become error-prone, difficult or impossible?

Dragon February 9, 2023 - 12:55 pm

> why is there even a technical possibility of not having an upstream branch?”

The server is not privileged: it too runs git, and it has no upstream to send things to.

Also, having branches from multiple upstream servers implies that there is not a one-to-one mapping between my local branches and the server. This is valuable when I’m handling a pull request from a contributor without write access to the repository: I can make a branch that has them as an upstream, then treat it exactly like the rest of my branches.

Sriram Vellanki June 14, 2021 - 10:56 pm

SCHKN, Appreciate your work. Very well explained. I have a question, Does origin refer to my local branch?.

schkn July 25, 2021 - 7:13 pm

Hello, no, origin refers to the remote repository, the actual Git server where the code is stored.

Rafiqul July 13, 2021 - 8:20 am

Great!!!!! Thank you very much. It works fine.

Darian Boggs June 29, 2022 - 7:16 pm

Good article.

Two possible typos:
1) Under “Set upstream branch using git push”, in the purple commentary text for ‘–set-upstream’, you omitted a ‘-‘. It should read ‘-–set-upstream’. In the code example it is correct.

2) Under “Using a bash alias”, you define a bash alias, ‘gp’, but then you don’t use it after the ‘git checkout -b branch2’ command.

Nandini Chaurasiya November 23, 2022 - 7:38 am

Why ‘master’ branch is used here ?
I just want to set upstream as origin for my feature branch. No where master is coming into picture.
“You created some commits in your branch, you want to set the tracking branch to be master.”


Leave a Comment

This site uses Akismet to reduce spam. Learn how your comment data is processed.