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

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 24, 2025, 20:01 UTC
Message-ID: <xmqqqzvvk4bj.fsf@gitster.g>
In-Reply-To: <be6453d010bdc9d2b49988d6841dd7e7f9bdf1f8.1758649472.git.gitgitgadget@gmail.com>

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 12 quoted lines

> -When the command line does not specify what to push with `<refspec>...`
> -arguments or `--all`, `--mirror`, `--tags` options, the command finds
> -the default `<refspec>` by consulting `remote.*.push` configuration,
> -and if it is not found, honors `push.default` configuration to decide
> -what to push (See linkgit:git-config[1] for the meaning of `push.default`).
> -
> -When neither the command-line nor the configuration specifies what to
> -push, the default behavior is used, which corresponds to the `simple`
> -value for `push.default`: the current branch is pushed to the
> -corresponding upstream branch, but as a safety measure, the push is
> -aborted if the upstream branch does not have the same name as the
> -local one.

That's a lot of text, and ...

Show 9 quoted lines

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

.. the above gives us vastly more pleasant readability improvement. Nice.

I do not know if you want to do anything to the lack of any punctuation at the end of sentences 1. and 2. (I would have written ';' if I were writing this myself).

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

This feels a bit out of place, as the safety measure, as I
understand it, is only relevant in 3. and only when push.default is
set to "simple".  If we are referring the user to the configuration
section, then it may be a better place to say that the "simple"
setting requires you to integrate with the branch with the same name.
 
Thanks.