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

From: Junio C Hamano <[email-masked]>
Date: Fri, 26 Sep 2025 12:03:31 -0700

"Julia Evans" <[email-masked]> 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/[email-masked]/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.

When b55e6775 (push: introduce new push.default mode "simple",
2012-04-24) introduced the "simple" mode, the intention was fairly
clear:

    push: introduce new push.default mode "simple"
    
    When calling "git push" without argument, we want to allow Git to do
    something simple to explain and safe. push.default=matching is unsafe
    when used to push to shared repositories, and hard to explain to
    beginners in some contexts. It is debatable whether 'upstream' or
    'current' is the safest or the easiest to explain, so introduce a new
    mode called 'simple' that is the intersection of them: push to the
    upstream branch, but only if it has the same name remotely. If not, give
    an error that suggests the right command to push explicitely to
    'upstream' or 'current'.
    
    A question is whether to allow pushing when no upstream is configured. An
    argument in favor of allowing the push is that it makes the new mode work
    in more cases. On the other hand, refusing to push when no upstream is
    configured encourages the user to set the upstream, which will be
    beneficial on the next pull. Lacking better argument, we chose to deny
    the push, because it will be easier to change in the future if someone
    shows us wrong.
    
    Original-patch-by: Jeff King <[email-masked]>
    Signed-off-by: Matthieu Moy <[email-masked]>
    Signed-off-by: Junio C Hamano <[email-masked]>

We did reject a "git push" (no other arguments) in an unconfigured
repository using push.default=simple.

We must have _broken_ it along the way somewhere over the years.

In the output from

  $ git log --all-match --grep=push.default --grep=simple

there are a handful of changes that touch PUSH_DEFAULT_SIMPLE in
ancient history; ed2b1829 (push: change `simple` to accommodate
triangular workflows, 2013-06-19), seems to have broken the
unconfigured case, which 00a6fa07 (push: truly use "simple" as
default, not "upstream", 2014-11-26) tried to fix it, and then
another commit e291c75a (remote.c: add branch_get_push, 2015-05-21)
further tweaked on the triangular (i.e. the remote you are pushing
to is different from the remote you are fetching from) workflow.

But that is long time ago; I do not think we can _fix_ the breakage
as that would be a big behaviour change.  If 'simple' works to
update the branch with the same name as your current branch at the
remote you cloned from without you having to do anything special,
such a convinience is something the existing users we acquired over
the past 10 years must have become very accustomed to already.  We
cannot break them.

    And that is my excuse for stopping to look into the detauls of
    these commits the above "git log" command found ;-)

> So it seems more accurate to say that push.default.simple will push
> to the branch with the same name, with the restriction that you might
> have to set an upstream, because the branch must always have the
> same name, but whether or not you have to set an upstream depends
> on the situation.

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?  You may have set an upstream in a way that is not
compatible with the "simple" mode and need to fix it, but otherwise,
it appears that the "simple" mode should always work for an
unsuspecting user who does not configure their repository and
remotes into some nonstandard shape.

And if so, perhaps we do not need any special warning/note to write
for a place where we talk about "git push" generally (as opposed to
where we talk about push.default=simple settings)?

Thanks.