Getting started with git set upstream
Git upstream is a link between the local repo and the remote one, and it enables you to synchronize the two repos. You will mostly apply
git set upstream when creating a repo or collaborating with other software engineers on a forked repo for the first time.
This tutorial explains the often confused git set upstream terms using step-by-step examples. After going through the tutorial, you should comfortably handle the typical git set upstream errors and easily contribute to projects you love.
You can set up and push changes to an upstream branch using the
## set and push changes on new remote git push --set-upstream <upstream URL> <upstream branch> ## set name git remote add <upstream name> <upstream URL> ## set on forked repo git remote add upstream <upstream URL>
commands or by following your remote repo's guidelines, as explained below.
Setup Lab Environment to explain git set upstream
We will work with two local and two remote repos in this tutorial. We will open the two repos with different browsers, Google Chrome and Microsoft Edge.
Use the first remote to configure a new repo in preparation for git set upstream. The second remote (in conjunction with the first one) enables us to fork and track changes across the local, origin, and upstream repos.
I am creating the first repo,
git_set_upstream, on Github account A using Google Chrome.
Let us head over to the second Github account B on Edge browser and create another repo called
Now that we have remote repos to play with let us view practical examples of git set upstream in action.
Example-1: git set upstream on a new repository
Git set upstream is crucial in keeping the local repo in sync with a remote one. Here's a scenario that would require you to configure an upstream branch properly.
You build an application, add and commit the changes to the local repo.
When the push time reaches, you head over to a remote repo service provider like Github's, Gitlab's or Bitbucket's website, and you create a remote repo, as we did on
You grab the clone URL, then move to the command line to push your code changes to the clone URL. That is when the git set upstream drama starts.
Let us mimic the condition described above.
Access a command line. Create a directory and some files. I am creating one called
git_set_upstream inside the
cd into the
git_set_upstream directory and create two files,
cd git_set_upstream touch index.html style.css
Add some code into the HTML and CSS files. For example, let us append some texts in each file, as follows:
echo html is awesome >> index.html
echo body >> style.css
Let us initialize a git repository, stage, and commit the changes.
git init git add . git commit -m "add html and css files"
Now is the time to push the changes to
git_set_upstream remote repo.
Move to the remote repo and grab the push URL.
git push to remote repo fails
If you run
git push <remote repo's URL>
on the command line, you will get this error:
Here, git implies, "You have told me the name of a remote branch to push your local changes to. But I can't proceed with this request because the two repos are not linked to talk to one another."
Let us git set upstream branch using the
--set_upstream flag specified in the error message.
Running the commands
git push --set-upstream https://github.com/Stevealila/git_set_upstream.git master
creates a new branch in a remote repo called
master and pushes changes to it.
Refresh the remote repo's page and inspect the branches tab to see the changes.
Setting an upstream branch makes subsequent push requests straightforward because we will not retype the lengthy push URL on subsequent requests. Instead, we only need to run the short push command:
Using remote repo's guidelines
You might have noticed that when we create a new Github repo without a
README.md file, the platform guides us to
git push the changes using the
Here are what the git set upstream terms mean:
originrefers to the remote repo's URL. origin, clone URL, or upstream can mean the same thing.
- If we clone the repo, git links local and remote URLs, so we don't go through the lengthy upstream setup process. That is why you use
git pushwithout manually configuring the upstream.
-uis the short form of upstream. It points to the repo where we push or pull changes.
You can configure the upstream further by specifying the remote name using the command:
git remote add <upstream name> <upstream URL>
For example, we set our upstream name to the above URL like this:
git remote add origin https://github.com/Stevealila/git_set_upstream.git
If you run into fatal: remote origin already exists error, use this command to remove the default origin
git remote rm origin
and set it to a new URL.
You can check the default git remote origin using the command:
git remote -v
After setting the upstream, you can use any of the three methods to interact with the upstream branch.
git push <upstream URL>for example,
git push https://github.com/Stevealila/git_set_upstream.git
git push <upstream-name> <upstream-branch>for example,
git push origin master
And voila, our changes are majestically moving to the remote repo!
Example-2: git set upstream when contributing to a project
Let us see another significant application of git set upstream.
forked_repo opened in Edge browser.
Get the clone URL.
clone the repo and
cd into it.
Let us modify its content, add, commit and push the changes
then refresh the page to see our changes.
Copy account B repo's URL and head to Google Chrome (where we logged in to account A) to access the repo and fork it.
Let us clone and track the forked copy locally.
Head over to the command line. Create another directory to clone the repo, thereby avoiding confusion between the parent and copy of the forked repo when managing the similar repo names.
We are managing a chain of three repositories; local, origin, and upstream repo's copy.
Let us check the repo we can access from the command line using the command:
git remote -v
Grab the forked_repo's URL. Move to the terminal and set the upstream with the following command
git remote add upstream https://github.com/Alilasteve/forked_repo
This time around, we are using
upstream instead of
origin is already in use.
Let us recheck the remote repos to confirm the configurations.
git remote -v
In terms of hierarchy,
upstream is the top-level repo followed by the
origin of our locally cloned repo.
Now we can pull down (also called fetch) the changes in the upstream by running
git fetch upstream
To test the command, navigate to
git_forked repo. Modify some files,
git add . and
git push the changes. Return to
git_forked_copy and run the command:
git fetch upstream
You should see changes similar to mine here:
Similarly, you can push changes to the upstream repo.
That is how you can contribute to another software engineer's project with the help of git set upstream.
Applying git set upstream saves you a ton of development, push and project collaboration time since you can manage a repo with minimal effort. Now that you know how to configure and speed up local and remote repo synchronization, you can apply the skills in your git missions.