From: Matthieu Moy <matthieu.moy@grenoble-inp.fr>
Date: Sun, 16 Jun 2013 18:48:41 GMT
Subject: Re: [PATCH] config doc: rewrite push.default section
Message-ID: <vpqvc5dj3hy.fsf@anie.imag.fr>
In-Reply-To: <1371377188-18938-1-git-send-email-artagnon@gmail.com>

Ramkumar Ramachandra <artagnon@gmail.com> writes:

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

I'd put it the other way around: the intuitive explanation first, and
the technical one after. For people not totally familiar with Git, the
first part does not make much sense (and when I learn a new tool, I
really don't like when the doc assumes I already know too much about
it).

Also, this $HEAD Vs HEAD doesn't seem very clear to me. I don't have a
really good proposal for a better wording, but maybe replacing $HEAD
with $branch would make a bit more sense, as having $HEAD != HEAD is
weird.

> +* `simple` - in central workflows, behaves like `upstream`, except
> +  that it errors out unless branch.$HEAD.merge is equal to $HEAD.

I'd reverse the sentense too. In your wording, I get the feeling that
erroring out is the normal flow, and pushing is the exception
("unless").

"... except that it errors out if branch.$HEAD.merge is not equal to
$HEAD." ?

> +  single command.  Dangerous, and inappropriate unless you are the
> +  only person updating your push destination.

Here also, I'd have said "Dangerous, and inappropriate if you are
not ...".

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/