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

From: Julia Evans <julia@jvns.ca>
Date: Sep 26, 2025, 22:27 UTC
Message-ID: <2b8193d1-f492-4cfd-b568-107d68112d9a@app.fastmail.com>
In-Reply-To: <xmqqa52havek.fsf@gitster.g>

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

Show 20 quoted lines

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

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

Show 53 quoted lines

> 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 <peff@peff.net>
>     Signed-off-by: Matthieu Moy <Matthieu.Moy@imag.fr>
>     Signed-off-by: Junio C Hamano <gitster@pobox.com>
>
> 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.

Show 14 quoted lines

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

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:

Show 8 quoted lines

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