What is the purpose of the `-u` parameter when running `git push`?

If you've ever read documentation, tutorials, or courses on Git to learn how to push your code to a remote repository, then you've surely seen this command somewhere:

git push -u origin master

You must be used to the push command, but you've also surely noticed this -u parameter that's often present yet optional.

So why should we add it? When should we do it and above all what's its use? That's what we're going to look at in this article.

An optional but recommended parameter

Let's start with the meaning of this parameter, which is actually a shorthand parameter.

"-u" replaces the "--set-upstream" parameter when calling the git push command, with no difference between the two parameters.

What does "set-upstream" mean?

When pushing changes from a local repository to a remote repository, Git can't guess that your local branch wants to be linked by default with a particular branch.

This remote branch, with which you can "link" your local branch, is what's called the "upstream".

Is it possible to work without an upstream? The answer is: yes. Nevertheless, it won't make things easier for you.

What does linking a branch mean?

Defining an upstream for your current branch simply means that you won't have to specify the name of the desired branch every time you want to do a git pull or a git push.

That's why it's recommended to use the -u parameter when you push a new branch to your remote repository:

git push -u origin branch
# you can then simply do
git push origin
# or
git pull origin
# without specifying the branch!