[PATCH] config doc: rewrite push.default section

From

Ramkumar Ramachandra <artagnon@gmail.com>

Date

Jun 16, 2013, 10:06 UTC

Message-ID

<1371377188-18938-1-git-send-email-artagnon@gmail.com>

Design by Junio.

Signed-off-by: Ramkumar Ramachandra <artagnon@gmail.com>
---
 I'll send in the implementation once we can agree that this is what
 we want.

 Documentation/config.txt | 51 ++++++++++++++++++++++++------------------------
 1 file changed, 25 insertions(+), 26 deletions(-)

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 7fd4035..30350a3 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -1832,33 +1832,32 @@ push.default::
 	line. 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.
-* `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.
+* `nothing` - error out unless a refspec is explicitly given.
+
+* `current` - push the refspec "$HEAD".  HEAD is resolved early to a
+  branch name (referred to as $HEAD).  In other words, push the
+  current branch to update a branch with the same name on the pushing
+  side.
+
+* `upstream` - push the refspec "$HEAD:branch.$HEAD.merge", and error
+  out if the push destination is not the same as branch.$HEAD.remote.
+  The name "upstream" refers to the revision "@{u[pstream]}" in
+  linkgit:gitrevisions[7].  It is useful in central workflows, to make
+  the `push` symmetrical to `pull`.
+
+* `simple` - in central workflows, behaves like `upstream`, except
+  that it errors out unless branch.$HEAD.merge is equal to $HEAD.  In
+  non-central workflows, behaves like `current`.  It will become the
+  default in Git 2.0.
+
+* `matching` - push the refspec ":".  In other words, push all
+  branches having the same name in both ends, even if it means
+  non-fast-forward updates.  This is for those who prepare all the
+  branches into a publishable shape and then push them out with a
+  single command.  Dangerous, and inappropriate unless you are the
+  only person updating your push destination.  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.443.g4fd77b9