On Fri, Sep 26, 2025, at 11:29 AM, Junio C Hamano wrote:

Junio C Hamano [off-list ref] writes:

quoted

quoted

But I'm not sure it's true in this case: we just said above that
"The default is `push.default=simple`, which will push to a branch with
the same name as the current branch."

So I think this simplified statement is what causes confusion.  It
says push.default=simple will push to such and such place, but that
is not true....

After sleeping on this, I do think that at the crux of confusing
wording in the current draft is the lack of stress on "simple" being
a narrower special case of more general "upstream" for various
push.default modes.  In either of these modes, unless told otherwise
with the configuration file or the command line arguments, "git
push" pushes to update the upstream of the current branch.  There
is, as you said, an additional safety measure in the "simple" mode,
that rejects a configuration to have a branch whose name is
different in the remote repository as the upstream branch.

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 (local)
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.

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.

Personally that behaviour seems unintuitive to me: I always
thought that push.default=simple _did_ require you to set an
upstream branch and after spending many hours thinking about I still
can't really describe in a way that feels satisfactory to me why
it sometimes doesn't and under what conditions that happens. 

One idea I had was to change Git's behaviour so that push.default=simple
_does_ require you to set an upstream branch, and then we could
document that behaviour. That's how it used to work when
push.default=simple was originally created and it's not clear to me if the
change to make push.default=simple _not_ always require you to
set an upstream was intentional or not. I did a git bisect to find out when
this changed, and it was in https://github.com/git/git/commit/ed2b18292bfeedc98c9e2b6bd8a35d8001dab2fc 
commit ed2b18292bfeed

I tried to write a patch to require setting an upstream branch, though my
commit message has some mistakes and I'm not at all sure of my
understanding of the code.
https://github.com/jvns/git/commit/3553479892b11c50de939707e7f00aa7c7cb2f9d

We should make our text clear enough that anybody who read about the
push.default=simple configuration easily understand the above.  We
would need to find a good division between what to put in the main
text and what to leave out to the "see ... for more detauls" part to
guide those who read about "git push" command to the same
realization without bombarding them with descriptions of full range
of possible values of push.default.

Peeking our earlier exchange to help me formulate my thinking a
bit...

quoted

+To decide which branches, tags, or other refs to push, Git uses
+(in order of precedence):
+
+1. The `<refspec>` argument(s) (for example `main` in `git push origin main`)
+   or the `--all`, `--mirror`, or `--tags` options
+2. The `remote.*.push` configuration for the repository being pushed to
+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.

... here is my attempt.

    3. The `push.default` configuration. The default is `simple`,
       which is a variant of `upstream`.  In either mode, "git push"
       updates the configured upstream branch (see the UPSTREAM
       BRANCHES section for more on how to set and use upstreams).
       The 'simple' mode has an additional limitation that the name
       of your configured upstream must be the same as your branch.

(iow, I rolled the "As a safety measure" paragraph into 3. itself).