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

Ingo Rohloff <lundril@gmx.de> writes:

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.