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

> From: Julia Evans <julia@jvns.ca>
> 
> 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>
> ---
>  Documentation/git-push.adoc | 28 +++++++++++++++-------------
>  1 file changed, 15 insertions(+), 13 deletions(-)
> 
> diff --git a/Documentation/git-push.adoc b/Documentation/git-push.adoc
> index acdf25e5cd..2848cf2e1f 100644
> --- a/Documentation/git-push.adoc
> +++ b/Documentation/git-push.adoc
> @@ -26,18 +26,20 @@ that isn't already on the remote.
>  The `<repository>` argument defaults to the upstream for the current 

>  or `origin` if there's no configured upstream.
> 
> -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 

> +   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,CONFIGURATION>> section below for more on

> `push.default`. +
> +`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,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
> @@ -696,7 +698,7 @@ a `git gc` command on the origin repository.
> 
>  include::transfer-data-leaks.adoc[]
> 
> -CONFIGURATION
> +CONFIGURATION[[CONFIGURATION]]
>  -------------