What does the -u parameter mean in git push -u origin master?

I've been using Bitbucket from Atlassian and when I need to push some data into my repository I have to type the following command:

git push -u origin master

In git documentation it's:

git push origin master

Why do we need that special -u parameter? What does it do?

1 Answer

The git manual for push (which can be viewed in the terminal with man git-push):

-u
--set-upstream

For every branch that is up to date or successfully pushed, add upstream (tracking) reference, used by argument-less git-pull[1] and other commands. For more information, see branch.<name>.merge in git-config[1].

Simply put, it sets the push target as current branch's upstream.

Once you've issued git push -u origin master on branch master, you can simply git push without extra arguments on that branch and it will be equivalent to git push origin master.

Note that branch names don't have to match. You can set your local master to push to origin/foo, although it will be confusing. You can also still push to branches other than upstream explicitly, it won't overwrite the upstream setting.

The upstream branch can be set without pushing using git branch -u origin/master. Note that origin/master is an argument for the -u option, not for the git branch command in general, hence it must be specified in the remoteName/branchName format rather than two separate arguments: remoteName branchName.