Subject: Documentation about "push.default=upstream" is confusing

From: Ingo Rohloff <[email-masked]>
Date: Sun, 9 Feb 2014 17:31:57 +0100

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