Select Page


Branches are one of the coolest things in git, and you must agree with me on that. Creating a branch allows you to manage your project workflow in a way you wouldn’t be able to do otherwise. When working on large projects, creating branches allows you to isolate a development pattern, work on a separate feature, and add it to the main code once you’re done. This method of supervising your code combines amazingly well with one of the other core concepts of git, which is to do commits. This allows you to roll back to any previous state of your project on demand.

The git branch command has a plethora of additional flags that you can pass along to achieve different outcomes. One of these is the –unset-upstream flag. Sometimes, when executing the git status command, you may be advised by the output to use this flag along with the git branch command to ‘fixup’ certain things to your commits or staged changes. 

In this article, we’ll try to clear up all the confusions you might have with this flag, along with their use cases that you yourself could benefit from.

Git Upstream Branches

Git upstream branches are remote branches hosted on GitHub, which you can access directly on your terminal using git. These branches are the ones you pull when using git clone. Basically, it’s the opposite for your local repositories. Upstream repositories hosted in GitHub or other similar services can be accessed via git subcommands and can also be pushed to the repository back after any updates you make, given that you have authorized access to that remote repository. So what does this have to do with the –unset-upstream flag? I’m glad you asked!

Before you can actually use the –unset-upstream flag, you need to be connected to a remote repository in the first place. The next section will walk you through the process of using the –unset-upstream flag under the git branch command.

Use of –unset-upstream flag

Git was initially designed as a version control system, but it is a lot more now that it used to be. Using Git, developers around the world can host their codes and programs without the extra hassle of a third party publisher. Hosting your program in GitHub is as easy and plain as uploading your source code and preparing a README for your users when they first land on your GitHub repository. Given how fast open-source programs are evolving, more and more developers willing to use Git and GitHub actually make a lot of sense.

Nevertheless, let us come to our main goal here, which is knowing how and why to use –unset-upstream flag. So essentially, when you want to make a direct connection between a remote repository’s branch and your local system, you’d use the “git branch –set-upstream <remote> <branch>” command. The same can be achieved using git push, but there’s a difference.

Using git push directly requires you to specify the branch and remote. On the other hand, if you set up an upstream branch, then you can only type out git push, and you’re done. Yes. This way you won’t need to specify the remote and branch every single time you make an update.

So to first setup an upstream branch, you’d use the following syntax of command in your terminal:

$ git branch --set-upstream <repository_name> <branch>

Once you’ve set up an upstream branch, you’re now good to go making commits to the remote repository. But what if you’re done with it? If you now need to set up a different upstream branch, you need to first disconnect the current one, before you can. This is exactly where you need to use the –unset-upstream flag. To disconnect the current upstream branch, you’d use:

$ git branch --unset-upstream <branch>

Your branch is based on ‘origin/master’…

This could very well be a common reason as to why you came here. Sometimes, when executing git status, you might end up getting an output like the one below:

On branch quickfix
Your branch is based on ‘origin/master’, but the upstream is gone.
    (use ‘git branch --unset-upstream’ to fixup)nothing to commit, 
working on tree clean

Sounds familiar? It sure does. But what does it actually mean, and why do you need to use the –unset-upstream flag?

Let’s say for example, you pulled a remote repository, and you’re on a different branch than origin/master. At this point, the master branch somehow got removed. And the next time when you try to do a commit, the sub-branch quickfix is trying to source the master branch, but is unable to find it. At this point, you’d need to use the “git branch –unset-upstream” command so that git status stops sourcing that upstream branch, which initially used to exist.


That is pretty much it about the –unset-upstream flag in git. While you’d hardly ever use the git branch –set-upstream command, other than on times when you’re working on a large project that requires frequent commits, it’s good to know a little about its use for sure. It is probably not recommended to do more commits than you need, though, as it populates your history in ways you’d find hard to recover old states of your project when you need them most.