What is the difference between git push.default=current and push.default=upstream?

Question

The man page for git-config lists these options for push.default:

nothing - do not push anything. matching - push all matching branches. All branches having the same name in both ends are considered to be matching. This is the default. upstream - push the current branch to its upstream branch. tracking - deprecated synonym for upstream. current - push the current branch to a branch of the same name. 

In most cases I would assume that pushing to a branch's upstream branch would be the same as pushing to a branch of the same name, since the upstream branch would normally have the same name, and since the branch of the same name ("current") would normally (or always, by definition?) be upstream. So what's the difference?

UPDATE: The man page for git-config has been updated (as one would expect), so the distinctions made there may be a lot clearer now.

Answer 1

You've summarized the difference in your question. upstream pushes to the configured upstream branch, while current assumes the upstream branch has the same name as the current local branch, and pushes to that specific name. In reality, there's no reason to assume a local branch's upstream tracking branch has the same name as the local branch itself.

For example, if you work in multiple repositories or across many shared developer remotes, you often end up tracking different forks of the same branch, such as allen-master or susan-master, both of which track the master branch in Allen and Susan's repos, respectively. In this case, current would be the incorrect setting, because those branch names don't exist on their remotes. upstream, however, would work just fine.

A more practical example might be tracking both a development and production repository. Your workflow might use a different mainline branch for each, but that might get confusing. Suppose you were a code integrator and wanted to track both repositories' master branches separately.

git checkout -b production --track production/master git checkout -b development --track development/master 

Now you've got two branches that track their respective repositories, neither of which use the master naming convention at all. There's little confusion about the branch names: They explicitly describe what they track. Nevertheless, push.default = current wouldn't make any sense as neither remote contains a development or production branch.