[PATCH 2/6] config doc: rewrite push.default section

[Ramkumar Ramachandra <artagnon@gmail.com>]

4d3592 (Merge branch 'rr/triangle', 2013-04-07) introduced support for
triangular workflows in Git, but the push.default values still assume
central workflows.  Rewrite the descriptions of `nothing`, `current`,
`upstream` and `matching` for greater clarity, and explicitly explaining
how they behave in triangular workflows.  Leave `simple` as it is for
the moment, as we plan to change its meaning to accommodate triangular
workflows in a later patch.

Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 Documentation/config.txt | 56 ++++++++++++++++++++++++++----------------------
 1 file changed, 30 insertions(+), 26 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 7fd4035..9f04f74 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -1826,39 +1826,43 @@ pull.twohead::
 	The default merge strategy to use when pulling a single branch.
 
 push.default::
-	Defines the action `git push` should take if no refspec is given
-	on the command line, no refspec is configured in the remote, and
-	no refspec is implied by any of the options given on the command
-	line. Possible values are:
+	Defines the action `git push` should take if no refspec is
+	explicitly given.  Different values are well-suited for
+	specific workflows; for instance, in a purely central workflow
+	(i.e. the fetch source is equal to the push destination),
+	`upstream` is probably what you want.  Possible values are:
 +
 --
-* `nothing` - do not push anything.
-* `matching` - push all branches having the same name in both ends.
-  This is for those who prepare all the branches into a publishable
-  shape and then push them out with a single command.  It is not
-  appropriate for pushing into a repository shared by multiple users,
-  since locally stalled branches will attempt a non-fast forward push
-  if other users updated the branch.
-  +
-  This is currently the default, but Git 2.0 will change the default
-  to `simple`.
-* `upstream` - push the current branch to its upstream branch
-  (`tracking` is a deprecated synonym for this).
-  With this, `git push` will update the same remote ref as the one which
-  is merged by `git pull`, making `push` and `pull` symmetrical.
-  See "branch.<name>.merge" for how to configure the upstream branch.
+* `nothing` - do not push anything (error out) unless a refspec is
+  explicitly given.  Very safe, but not very convenient.
+
+* `current` - push the current branch to update a branch with the same
+  name on the receiving end.  Works in both central and non-central
+  workflows.  Equivalent to pushing the refspec "$branch" ($branch is
+  the name of the current branch).
+
+* `upstream` - push the current branch to a branch with the name
+  branch.$branch.merge on the receiving end, and error out if the push
+  destination is not the same as branch.$branch.remote.  The name
+  "upstream" refers to "@{u[pstream]}" in linkgit:gitrevisions[7],
+  which makes sense only if both branch.$branch.remote and
+  branch.$branch.merge are set.  It makes sure that a `push` is
+  symmetrical to `pull` in central workflows, and cannot be used in
+  non-central workflows.
+
 * `simple` - like `upstream`, but refuses to push if the upstream
   branch's name is different from the local one. This is the safest
   option and is well-suited for beginners. It will become the default
   in Git 2.0.
-* `current` - push the current branch to a branch of the same name.
+
+* `matching` - push all branches having the same name on both ends
+  (essentially ignoring all newly created local branches).
+  Well-suited for those who want to batch-update a specific set of
+  branches they consistently work on.  Use with caution, especially
+  when pushing with '--force'.  Equivalent to pushing the refspec ":".
+  This is currently the default, but Git 2.0 will change the default
+  to `simple`.
 --
-+
-The `simple`, `current` and `upstream` modes are for those who want to
-push out a single branch after finishing work, even when the other
-branches are not yet ready to be pushed out. If you are working with
-other people to push into the same shared repository, you would want
-to use one of these.
 
 rebase.stat::
 	Whether to show a diffstat of what changed upstream since the last
-- 
1.8.3.1.454.g30263f3.dirty