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

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

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

> On Fri, Sep 26, 2025, at 3:03 PM, Junio C Hamano wrote:
>> "Julia Evans" <julia@jvns.ca> writes:
>>
>>>> In other words, the push.default=simple mode does not tell Git to
>>>> push to a branch with the same name.  Rather, as a variant of the
>>>> push.default=upstream mode, it tells Git to follow the same "push to
>>>> the upstream branch" rule, which requires you to configure your
>>>> upstream.  But the mode gives additional limit on the name of the
>>>> branch that can be set to upstream.
>>>
>>> I like the idea of explaining it as "push.default=simple uses the
>>> configured upstream branch, with the restriction that the upstream
>>> branch must have the same name".
>>>
>>> But as I learned from you earlier in this thread: https://lore.kernel.org/git/pull.1964.v2.git.1757703309.gitgitgadget@gmail.com/T/#m896f4a32ca462d69637b56f9bdfaa61e55e6b952
>>> push.default=simple will sometimes push the current branch
>>> to the remote branch with the same name even if there's no configured
>>> upstream branch.
>>
>> It was not me teaching anybody, though.  I was showing my puzzlement
>> and confusion.
>> Now, I am still confused as I was when I wrote the message you
>> cited earlier.
>>
>> Do we ever have a case where, with the "simple" mode, you have to
>> set an upstream?
>
> Yes. If you clone a repository, create a new branch, and run  `git push`
> (to push to `origin`), Git will complain that you haven’t set an upstream
> for that branch, like this:
>
>     $ git push
>     fatal: The current branch testtesttesttest has no upstream branch.
>     To push the current branch and set the remote as upstream, use
>     
>         git push --set-upstream origin testtesttesttest
>     To have this happen automatically for branches without a tracking
>     upstream, see 'push.autoSetupRemote' in 'git help config'

Hmph, that contradicts with the observation we had in the message
you cited earlier, but it does reproduce for me as well.  Puzzled
again.

> My best guess from my experimentation and from reading some
> of the commit messages/code is that the rules for how
> `push.default=simple` works are something like:
>
> 1. If the remote you're pushing to is the remote that `git pull`
>    would normally pull from if run without any arguments,
>    then require the user to set an upstream
>    (with the idea that the remote is somehow "special"
>    and should be protected from accidental pushes)

This is the traditional 'simple'


> 2. Otherwise, push to the branch to with the same name
>    without requiring an upstream to be set

This is what 'triangular' feature we saw earlier in the "git log"
output in my message you are responding to had a few commits for.

> That said, the exact details of how push.default=simple works
> (ironically) seem complicated enough that I don't think it's worth
> documenting in detail at the beginning of the `git push` man page.

Totally agreed.

> To go back to the original text I suggested:
>
>> 3. The `push.default` configuration. The default is `push.default=simple`,
>>    which will push to a branch with the same name as the current branch.
>>    See the CONFIGURATION section below for more on `push.default`.
>> 
>> 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.
>
> The words "may fail" are definitely vague, and I agree it doesn't feel good
> to give a vague explanation like this. But if we think the current
> behaviour is "broken" and hard to understand and that we have to keep it for
> backwards compatibility reasons, giving a slightly vague explanation
> (perhaps with a reference to where someone can read all the gritty
> details) might be the best path.

OK.  Thanks for helping me think this through.