doc: git-push: clarify "what to push"

From user feedback: 6 users says they found the "what to push" paragraphs confusing, for many different reasons, including: * what does "..." in <refspec>... mean? * "consult XXX configuration" is hard to parse * it refers to the `git-config` man page even though the config information for `git push` is included in this man page under CONFIGURATION * the default ("push to a branch with the same name") is what they use 99% of the time, they would have expected it to appear earlier instead of at the very end * not understanding what the term "upstream" means in Git ("are branches tracked by some system besides their names?"") Also, the current explanation of `push.default=simple` ("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.") is not accurate: `push.default=simple` does not always require you to set a corresponding upstream branch. Address all of these by * using a numbered "in order of precedence" list * giving a more accurate explanation of how `push.default=simple` works * giving a little bit of context around "upstream branch": it's something that you may have to set explicitly * referring to the new UPSTREAM BRANCHES section The default behaviour is still discussed pretty late but it should be easier to skim now to get to the relevant information. In "`git push` may fail if...", I'm intentionally being vague about what exactly `git push` does, because (as discussed on the mailing list) the behaviour of `push.default=simple` is very confusing, perhaps broken, and certainly not worth trying to explain in an introductory context. `push.default.simple` sometimes requires you to set an upstream and sometimes doesn't and the exact conditions under which it does/doesn't are hard to describe. Signed-off-by: Julia Evans <julia@jvns.ca> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Julia Evans committed Oct 6, 2025 at 18:58 UTC 6e1688f1f462d7a704bbcc1dae612488b7ac6e29
1 file changed +15 -12
Documentation/git-push.adoc
+15 -12
@@ -26,18 +26,20 @@ that isn't already on the remote.
26 The `<repository>` argument defaults to the upstream for the current branch,
27 or `origin` if there's no configured upstream.
28
29 -When the command line does not specify what to push with `<refspec>...`
30 -arguments or `--all`, `--mirror`, `--tags` options, the command finds
31 -the default `<refspec>` by consulting `remote.*.push` configuration,
32 -and if it is not found, honors `push.default` configuration to decide
33 -what to push (See linkgit:git-config[1] for the meaning of `push.default`).
34 -
35 -When neither the command-line nor the configuration specifies what to
36 -push, the default behavior is used, which corresponds to the `simple`
37 -value for `push.default`: the current branch is pushed to the
38 -corresponding upstream branch, but as a safety measure, the push is
39 -aborted if the upstream branch does not have the same name as the
40 -local one.
29 +To decide which branches, tags, or other refs to push, Git uses
30 +(in order of precedence):
31 +
32 +1. The `<refspec>` argument(s) (for example `main` in `git push origin main`)
33 + or the `--all`, `--mirror`, or `--tags` options
34 +2. The `remote.*.push` configuration for the repository being pushed to
35 +3. The `push.default` configuration. The default is `push.default=simple`,
36 + which will push to a branch with the same name as the current branch.
37 + See the <<CONFIGURATION,CONFIGURATION>> section below for more on `push.default`.
38 +
39 +`git push` may fail if you haven't set an upstream for the current branch,
40 +depending on what `push.default` is set to.
41 +See the <<UPSTREAM-BRANCHES,UPSTREAM BRANCHES>> section below for more
42 +on how to set and use upstreams.
43
44 You can make interesting things happen to a repository
45 every time you push into it, by setting up 'hooks' there. See
@@ -702,6 +704,7 @@ a `git gc` command on the origin repository.
704
705 include::transfer-data-leaks.adoc[]
706
707 +[[CONFIGURATION]]
708 CONFIGURATION
709 -------------
710