Documentation about "push.default=upstream" is confusing

Hello,

I recently started to use git and now are digging through more and more of the low level details.

What I recently tried was to do this for a repository created by Bob:

  git remote add -t for_bob anna <url>

So setup a remote (created by anna) for which a branch called "for_bob" is fetched. Then "git fetch anna".

Then
  git checkout -b from_anna anna/for_bob

So create a "from_anna" branch in Bobs repository which tracks the "for_bob" branch in the remote "anna" repository.

Now "git pull" works as expected for the "from_anna" branch.

But "git push" does not, because "from_anna" has a different branch name than the branch you want to push to (you want to push to the "for_bob" branch).

So after googling I found out about the "push.default=upstream" config option, which seems to do exactly what I want: It uses the tracking information to decide to which remote branch I want to push.

Now for cross checking I looked up the documentation of "push.default" at http://git-scm.com . It says:

----- snip ------ push.default ...

upstream - push the current branch back to the branch whose changes are usually integrated into the current branch (which is called @{upstream}). This mode only makes sense if you are pushing to the same repository you would normally pull from (i.e. central workflow).

----- snip -----

I think the second sentence here is quite confusing. To me it seems "push.default=upstream" is actually the best choice for a *de-centralized* workflow.

Rationale: Assume I pull the "master" branch from several remote repositories (de-centralized workflow I guess).

To handle that I setup several remote tracking branches called:
  repo1_master   (tracks repo1/master)
  repo2_master   (tracks repo2/master)
  reap3_master   (tracks repo3/master)

Now without "push.default=upstream" I would have to either always explicitly
do something like:
  git push repo1 repo1_master:master
  git push repo2 repo2_master:master

Or modify ".git/config" to add that per default via "push=" entries.

Whereas with "push.default=upstream" everything works as expected it seems.

So if I am not wrong here, I would propose to rephrase the sentence ------ snip ----- This mode only makes sense if you are pushing to the same repository you would normally pull from (i.e. central workflow). ------ snip -----

To do that: Could someone point out, when it does NOT make sense to use "push.default=upstream" ?

with best regards
  Ingo