Re: [PATCH] config doc: rewrite push.default section

["Philip Oakley" <philipoakley@iee.org>]

From: "Ramkumar Ramachandra" <artagnon@gmail.com>
Sent: Sunday, June 16, 2013 11:06 AM
> Design by Junio.
>
> By detaching descriptions from the implementation, we're only 
> confusing
> users.  I've chosen to use the term "central workflow" to make the
> descriptions terse and readable, although I've stayed way from
> "triangular workflow" (referred to as non-central workflow).

A sentence, in the Documentation/config.txt, is needed to clarify the 
Central workflow and any distinction with the  non-central workflow(s). 
We cannot assume the new reader has the same world view of that concept 
(they may be thinking it means we do a centralised VCS, not a DVCS with 
a chosen central primary repo - assuming I have understood it 
correctly).

It took a while to bottom out the issues, so it is worth summarising the 
key point(s) in the documentation to avoid having to repeat the 
disussions ;-)

>
> Yes, I hate writing documentation but I have no choice if I want to
> update the implementations to do something sane in triangular 
> workflows.
>
> 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

s/In other words,/That is,/
'In other words' often indicates poor wording, while here the extra 
words explicitly explain the effect.

> +  current branch to update a branch with the same name on the pushing
> +  side.

s/pushing side/push destination/ for consistency with upstream wording 
used below.

> +
> +* `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

"Dangerous and innappropriate" (which it maybe for some) is too 
judgemental.
Perhaps turn it around to a positive (unless -> only if).

"Useful if 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
>
> --
regards
Philip