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

From: D. Ben Knoble <ben.knoble@gmail.com>
Date: Aug 28, 2025, 14:25 UTC
Message-ID: <CALnO6CBTx=5Eo4WGW7HVMO1TQLmJ_kVdHDOsHf4ok_nPEER5WA@mail.gmail.com>
In-Reply-To: <ac554cbe75444880bbb2791c4d85dcf083d833d7.1756240823.git.gitgitgadget@gmail.com>

On Tue, Aug 26, 2025 at 4:40 PM Julia Evans via GitGitGadget <gitgitgadget@gmail.com> wrote:

Show 5 quoted lines

>
> From: Julia Evans <julia@jvns.ca>
>
> - Be more explicit about what we're describing ("which branches" instead
>   of "what to push")

Reading this, I thought we would lose precision ("refspec" -> "branches"), but: the patch (correctly) includes more than branches. Perhaps

    - Be more explicit about what we're describing ("which branches,
[etc.]" instead of "what to push")

Show 46 quoted lines

> - Split out the ways to specify which branches into a numbered list,
>   since there are 5 different ways to specify it and it's a lot to parse
>   in paragraph form
> - The explanation of "push.default=simple" is confusing to some users,
>   use an explanation more similar to the one in `man git-config`
> - Mention the most common case where push.default=simple is likely to
>   fail, and how to handle it
>
> Signed-off-by: Julia Evans <julia@jvns.ca>
> ---
>  Documentation/git-push.adoc | 23 +++++++++++++----------
>  1 file changed, 13 insertions(+), 10 deletions(-)
>
> diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
> index 5c934486c33d..0232195515c9 100644
> --- a/Documentation/git-push.adoc
> +++ b/Documentation/git-push.adoc
> @@ -27,18 +27,21 @@ argument (for example `git push dev`), then if that's not specified the
>  `branch.*.remote` configuration for the current branch, and then defaults
>  to `origin`.
>
> -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`).
> +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 current branch
> +3. The `push.default` configuration (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.
> +push, the current branch is pushed to the branch with the same name
> +on the remote. The current branch must have a configured upstream with
> +the same name, so this will fail when pushing a new branch.
> +You can run `git push -u <repository> <current-branch>`
> +to configure the upstream.

I think we've lost the mention of `push.default` here, which we'd probably like to keep?

Also, I (personally) dislike teach "git push -u <repo> <branch>"
because it leads to some confusion. Let me try to explain myself:
- The way Git treats the configured upstream is the place to pull
from, merge from, rebase onto, etc., configured by branch.X.merge and
branch.X.remote. There is a (possibly!) separate "push to" place
configured (somewhat confusingly) with push.default and
remote.pushDefault.
- The way GitHub and others encourage setting upstream to the place
you push means you have to work a bit harder to pull, merge, rebase
from the semantic upstream (the thing you forked from, not the place
you push to): "git pull <remote> <branch>", "git rebase origin/main",
etc.
- There is, of course, another way that upstream is used: for
"ahead-behind" information in Git's status output. It is convenient to
know where you stand, and Git unfortunately does not provide an easy
way to see the same information against @{push} instead of
@{upstream}. I use some version of "git show-branch HEAD HEAD@{push}"
and a custom "git-div" script [1] for this…

Anyway, point is, I think defaulting to @{upstream} as the place you push has a nice benefit ("git status" shows me when I haven't pushed recently), but also is specific to a workflow where you push and pull from the same places. I find that _most_ of the time I'm actually doing something triangular (even when I push to and pull from the same repository, I rarely push to and pull from the same _branch_), and configuring things a different way affords me many other conveniences. For example, "git push" and "git pull" without extra flags are arguments just DWIM.

The confusion I alluded to earlier is that folks rarely learn this is an option and (in my estimation) lose out on an essential aspect of what makes Git distributed as opposed to centralized. It also leads to some confusion over what the term upstream means. And the extra "push.default explanation is sometimes inaccurate" doesn't help :)

I don't think this is a blocker for this patch, but I do have a bit of a knee-jerk reaction to this particular piece of (common-on-the-internet) advice :) Hope that makes sense.

[1]: https://github.com/benknoble/Dotfiles/blob/master/links/bin/git-div

PS I seek a better way to explain this whole idea, so my apologies for the confused rant.

-- 
D. Ben Knoble