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

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

Address all of these by using a numbered "in order of precedence" list
(similar to the previous commit), by giving a little bit of context
around "upstream branch": it's something that you may have to set
explicitly, and 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.

Signed-off-by: Julia Evans <[email protected]>

Author: jvns

Documentation/git-push.adoc

@@ -27,18 +27,20 @@ argument (for example `git push dev`), then if that's not specified the
 upstream 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`).
-
-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.
+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`.
+
+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.
 
 You can make interesting things happen to a repository
 every time you push into it, by setting up 'hooks' there.  See