The upstream branch of some local branch is the branch into which the
commits on that local branch should eventually be merged, usually
something like origin/master. For the master branch itself the
upstream branch and the branch it is being pushed to, are usually the
same remote branch. But for a feature branch the upstream branch and
the branch it is being pushed to should differ.
The commits on feature branches too should eventually end up in a
remote branch such as origin/master or origin/maint. Such a branch
should therefore be used as the upstream. But feature branches
shouldn’t be pushed directly to such branches. Instead a feature
branch my-feature is usually pushed to my-fork/my-feature or if you
are a contributor origin/my-feature. After the new feature has been
reviewed, the maintainer merges the feature into master. And finally
master (not my-feature itself) is pushed to origin/master.
But new features seldom are perfect on the first try, and so feature branches usually have to be reviewed, improved, and re-pushed several times. Pushing should therefore be easy to do, and for that reason many Git users have concluded that it is best to use the remote branch to which the local feature branch is being pushed as its upstream.
But luckily Git has long ago gained support for a push-remote which
can be configured separately from the upstream branch, using the
variables branch.<name>.pushRemote and remote.pushDefault. So we no
longer have to choose which of the two remotes should be used as "the
remote".
Each of the fetching, pulling, and pushing transient commands features
three suffix commands that act on the current branch and some other
branch. Of these, p is bound to a command which acts on the
push-remote, u is bound to a command which acts on the upstream, and e
is bound to a command which acts on any other branch. The status
buffer shows unpushed and unpulled commits for both the push-remote
and the upstream.
It’s fairly simple to configure these two remotes. The values of all
the variables that are related to fetching, pulling, and pushing (as
well as some other branch-related variables) can be inspected and
changed using the command magit-branch-configure, which is available
from many transient prefix commands that deal with branches. It is
also possible to set the push-remote or upstream while pushing (see
Pushing).