On Fri, Sep 26, 2025, at 3:03 PM, Junio C Hamano wrote:

"Julia Evans" [off-list ref] writes:

quoted

quoted

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.

It was not me teaching anybody, though.  I was showing my puzzlement
and confusion.

Oh, I'm glad I'm not the only one who's been confused about how
`push.default=simple` behaves :)

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 [off-list ref]
    Signed-off-by: Matthieu Moy [off-list ref]
    Signed-off-by: Junio C Hamano [off-list ref]

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.

That makes sense, can’t break backwards compatibility.

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

quoted

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?

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'

I use `push.default=simple` and this has happened to me a lot in the
past, personally I set `push.autoSetupRemote` to deal with this.

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)
2. Otherwise, push to the branch to with the same name
   without requiring an upstream to be set

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.
I definitely haven't been able to fully understand what they are yet.
Certainly it's true that sometimes you have to set an upstream
and sometimes you don't.

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.

I do like the idea (that I think you mentioned before) of adding a very
simple sentence like this near the beginning explaining what
`git push origin main` does, since it's easy to explain, and someone could
easily successfully start using `git push` without knowing any other
information.

`git push origin main` will push the local `main` branch to the `main`

branch on `origin`.