Re: [PATCH v3 4/4] doc: git-push: clarify "what to push"

[Junio C Hamano <gitster@pobox.com>]

"Julia Evans" <julia@jvns.ca> writes:

>>> +As a safety measure, `git push` may fail if you haven't set an upstream
>>> +for the current branch, depending on what `push.default` is set to.
>>> +See the UPSTREAM BRANCHES section below for more on how to set and
>>> +use upstreams.
>>
>> This feels a bit out of place, as the safety measure, as I
>> understand it, is only relevant in 3. and only when push.default is
>> set to "simple".  If we are referring the user to the configuration
>> section, then it may be a better place to say that the "simple"
>> setting requires you to integrate with the branch with the same name.
>
> That makes sense. My goal here is really to communicate that you may need
> to set an upstream for `git push` to work, since it hasn't been mentioned yet
> that the upstream branch might be involved in deciding what remote branch
> to push to, and it comes up pretty often when using the command.

Actually, I think it is a mistake to tell people to use unadorned
"git push" all the time.  Have them say "git push origin mytopic",
get them feel sick of doing so all the time, and then tell them they
do not have to if they set an upstream for the current branch.  IOW,
"sometimes you need to" is the source of the confusion that comes
from giving them too much DWIMmery.  You'd by default need to tell
Git, because you know more about your project than Git does, until
you tell Git once, after which Git knows what to do.

> Perhaps this instead:
>
> "Depending on the value of `push.default`, git push` may fail if the current
> branch doesn't have a configured upstream branch.
> See the UPSTREAM BRANCHES section below for more on how to set and
> use upstreams."

So, rather, something like this

    "git push" needs to know what branch to push to update what
    branch of which repository.  It is done by giving command line
    arguments and/or setting configuration variables to the command.
    See UPSTREAM BRANCHES section for more information.

would be more in line with a preferrable mindset users would have to
successfully use "git push", I think.