Documentation about "push.default=upstream" is confusing

Documentation about "push.default=upstream" is confusing

[Ingo Rohloff]

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

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

[Junio C Hamano]

Ingo Rohloff <lundril@gmx.de> writes:

> 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

If you think about your interaction with people who are only looking
at "repo1" alone, you _are_ using a centralized workflow.  You are
not the only one who update their 'master'; other people push there
to update that 'master' and you pull it in to keep you up to date
and further build your changes on top.  Such an interaction with
other people by using repo1 as the shared meeting point is well
served by the push-to-upstream mechanism, and that kind of
interaction is called "centralized workflow".  The illustration from
you is running one centralized workflow with each of the three
repositories.

The de-centralized workflow the message hints (but does not talk
about) is different.  It is not uncommon to pull from one place and
then to push the result out to your own publishing branch
(e.g. clone from anna, fetch to keep up to date with her, work on
it, publish to your repository to tell her to fetch from you), and
push-to-upstream is not very well suited for that topology.  You may
clone her "for-bob" branch, but you do not push it back to her
repository to update her "for-bob" branch.