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

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 26, 2025, 23:07 UTC
Message-ID: <xmqqecrsak3h.fsf@gitster.g>
In-Reply-To: <2b8193d1-f492-4cfd-b568-107d68112d9a@app.fastmail.com>

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

Show 38 quoted lines

> 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.

Show 9 quoted lines

> 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.

Show 17 quoted lines

> 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.