Git fork

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>

authored by

Julia Evans and committed by
Junio C Hamano
6e1688f1 3856d893

+14 -11
+14 -11
Documentation/git-push.adoc
··· 26 26 The `<repository>` argument defaults to the upstream for the current branch, 27 27 or `origin` if there's no configured upstream. 28 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`). 29 + To decide which branches, tags, or other refs to push, Git uses 30 + (in order of precedence): 34 31 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. 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. 41 43 42 44 You can make interesting things happen to a repository 43 45 every time you push into it, by setting up 'hooks' there. See ··· 702 704 703 705 include::transfer-data-leaks.adoc[] 704 706 707 + [[CONFIGURATION]] 705 708 CONFIGURATION 706 709 ------------- 707 710