Merge branch 'mm/simple-push'

New users tend to work on one branch at a time and push the result
out. The current and upstream modes of push is a more suitable default
mode than matching mode for these people, but neither is surprise-free
depending on how the project is set up. Introduce a "simple" mode that
is a subset of "upstream" but only works when the branch is named the same
between the remote and local repositories.

The plan is to make it the new default when push.default is not
configured.

By Matthieu Moy (5) and others
* mm/simple-push:
  push.default doc: explain simple after upstream
  push: document the future default change for push.default (matching -> simple)
  t5570: use explicit push refspec
  push: introduce new push.default mode "simple"
  t5528-push-default.sh: add helper functions
  Undocument deprecated alias 'push.default=tracking'
  Documentation: explain push.default option a bit more

1 files changed, 22 insertions, 4 deletions

diff --git a/Documentation/config.txt b/Documentation/config.txt
index 83ad8ebce0..40a6e8fb89 100644
--- a/Documentation/config.txt
+++ b/Documentation/config.txt
@@ -1683,12 +1683,30 @@ push.default::
 	line. Possible values are:
 +
 * `nothing` - do not push anything.
-* `matching` - push all matching branches.
-  All branches having the same name in both ends are considered to be
-  matching. This is the default.
+* `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` - deprecated synonym for `upstream`.
+  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.
+  +
+  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