Re: [PATCH 1/7] Documentation: explain push.default option a bit more

Matthieu Moy [off-list ref] writes:

The previous documentation was explaining _what_ the options were doing,
but were of little help explaining _why_ a user should set his default to
either of the options.

Thanks.

 * `nothing` - do not push anything.
+* `matching` - push all branches having the same name in both ends.
+  This allows those who prepare all the branches into a publishable
+  shape to push them out to a non-shared repository with a single
+  command. This is well suited when pushing to a non-shared
+  repository, but may give surprising results when used on a
+  repository shared by multiple users, since locally stalled
+  branches will attempt a non-fast forward push if other users
+  updated the branch remotely. This is the default.

The thought does not flow smoothly with the repetition of "non-shared"
here.  How about rephrasing it a bit, perhaps like this?

  * `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 the default.

+* `upstream` - push the current branch to its upstream branch. See
+  "branch.<name>.merge" for how to configure the upstream branch. This
+  makes `git push` and `git pull` symmetrical in the sense that `push`
+  will update the same remote ref as the one which is merged by
+  `git pull`.

Reordering the sentences may make it read better; first tell the reader
why and what enough so that they can decide if this is good for her and
then tell her how to configure it.

  * `upstream` - push the current branch to its upstream branch. 

    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. 

 * `tracking` - deprecated synonym for `upstream`.
 * `current` - push the current branch to a branch of the same name.
+  +
+  The `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. They are safe when
+  pushing to a shared repository.

Do we really want to say "safe" here?  I think it is misleading in
multiple ways.

 - If your current branch has a name differnt from its upstream, using
   `current` when you meant `upstream` may result in the embarrasing
   fast forward discussed elsewhere, which is hardly "safe".

 - If you always make everything on your end ready before pushing things
   out, `matching` may attempt to update remote branches other than the
   one that corresponds to your current branch, but that is exactly what
   you want to see---there is no danger here.  You can make it dangerous
   with --force, but that is a separate issue.

 - An attempt to push a stale branch in all cases will error out without
   causing damage to the remote repository.  If you do not keep your
   branches up-to-date and still use `matching`, you have more chance of
   seeing this when used against a shared repository. It is unclear if
   the use of word "safe" in the above description means this "you are
   behind" error "a risk to be avoided", but

    - if so, `current` or `upstream` will see the same error in a shared
      repository where the same branch is updated by multiple people, so
      "They are safe" is not quite correct; and

    - if not, then `matching` is not less safe than others (it is just
      as safe and unsafe as `current`).

There is a high correlation between use of shared repository and the
style of "working on one branch at a time, pushing the result as soon as
that single branch is OK", so I am perfectly fine with saying that these
single-branch modes are most likely what people want to use when working
with a shared repository, but I do not think `safety` has much to do
with the choice.