When doing a 'git push', what does '--set-upstream' do?

What does git --set-upstream do?

I tried to understand it by reading the git manual, but I didn't quite get it.

To avoid confusion,
recent versions of git deprecate this somewhat ambiguous --set-upstream option
in favor of a more verbose --set-upstream-to option
with identical syntax and behavior.
[ Reference ]

git branch --set-upstream-to <remote-branch>

sets the default remote branch for the current local branch.

Any future git pull command (with the current local branch checked-out),
will attempt to bring in commits from the <remote-branch> into the current local branch.

git push -u origin <local-branch>

This automatically creates an upstream counterpart branch for any future push/pull attempts from teh current <local-branch>. The upstream remote branch derived from the branch name - <local-branch> is also configured as the default for all subsequent actions like push/pull etc.

For example, executing the above command for <local-branch> = test,
will result in creating a <remote branch> = remotes/origin/test.

Note: One way to avoid having to explicitly type --set-upstream / --set-upstream-to is to use its shorthand flag -u.

For more details, check out this detailed explanation about upstream branches and tracking.