git set upstream Explained [Practical Examples]

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 forked_repo.

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 git_set_upstream.

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 golinux directory.

mkdir git_set_upstream

cd into the git_set_upstream directory and create two files, index.html, and style.css.

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:

git push

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 -u flag.

Here are what the git set upstream terms mean:

1. origin refers to the remote repo's URL. origin, clone URL, or upstream can mean the same thing.
2. 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 push without manually configuring the upstream.
3. -u is 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.

1. git push <upstream URL> for example,

   git push https://github.com/Stevealila/git_set_upstream.git

2. git push <upstream-name> <upstream-branch> for example, git push origin master
3. git push

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.

Head to 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 because 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.

 

Conclusion

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.