6.6.1 The Two Remotes

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