Re: [PATCH v3 0/4] doc: git-push: clarify DESCRIPTION section

>
> I surveyed 16 Git users about the git push man page. Here's a rewrite of the
> DESCRIPTION section and the definition of <refspec> based on the feedback.
> The goal is to clarify it while communicating the same information. The most
> common piece of feedback was that folks didn't understand what the term
> "ref" means. Most of the users who said they did not understand the term
> "ref" have been using Git for 10+ years.
>
> changes in v2:
>
>  * The biggest change is to add a new UPSTREAM BRANCHES section to explain
>    what an upstream is
>  * Drop the "refspec" changes from this patch series, I've made revisions to
>    them based on the comments here but I felt like this was getting too big.
>  * Added some backticks `` that I'd missed, from Ben's review
>  * From Junio's review, "The current branch must have a configured upstream
>    with the same name, so this will fail when pushing a new branch" was not
>    true, so replace it with a less detailed but hopefully true statement.
>    After a very long conversation with Ben I realized that actually
>    push.default=simple's behaviour is not really that simple (perhaps I
>    should think of it as more "safe" than "simple", since "current" seems
>    simpler), so it's more realistic to refer any questions to the
>    CONFIGURATION section which describes the behaviour in more detail.
>  * Rewrite all the commits to explain the problem they're trying to solve &
>    thinking behind them in more detail. Let me know if I added too much /
>    not enough detail.
>
> changes in v3:
>
>  * mention that git push also needs to send data in addition to updating the
>    branch, from Junio's review
>  * fix a newline, from Junio's review
>  * un-rename urls-remotes.adoc, from Junio's review
>  * mention pushRemote and git checkout in the UPSTREAM BRANCHES section and
>    be clearer about what's meant by "the relationship between the current
>    branch and the upstream", from Junio's review
>  * fix AsciiDoc formatting issue, from Junio's review
>
> Julia Evans (4):
>   doc: git-push: clarify intro
>   doc: add an UPSTREAM BRANCHES section to pull/push/fetch
>   doc: git-push: clarify "where to push"
>   doc: git-push: clarify "what to push"
>
>  Documentation/git-push.adoc     | 43 +++++++++++++++++---------------
>  Documentation/urls-remotes.adoc | 44 ++++++++++++++++++++++++++++++---
>  2 files changed, 64 insertions(+), 23 deletions(-)
>
>
> base-commit: c44beea485f0f2feaf460e2ac87fdd5608d63cf0
> Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1964%2Fjvns%2Fclarify-push-v3
> Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1964/jvns/clarify-push-v3
> Pull-Request: https://github.com/gitgitgadget/git/pull/1964
>
> Range-diff vs v2:
>
>  1:  270edd2b00 ! 1:  2870c77e80 doc: git-push: clarify intro
>      @@ Documentation/git-push.adoc: SYNOPSIS
>       -every time you push into it, by setting up 'hooks' there.  See
>       -documentation for linkgit:git-receive-pack[1].
>       +Updates one or more branches, tags, or other references in a remote
>      -+repository from your local repository.
>      ++repository from your local repository, and sends all necessary data
>      ++that isn't already on the remote.
>
>        When the command line does not specify where to push with the
>        `<repository>` argument, `branch.*.remote` configuration for the
>      @@ Documentation/git-push.adoc: corresponding upstream branch, but as a safety meas
>       +You can make interesting things happen to a repository
>       +every time you push into it, by setting up 'hooks' there.  See
>       +documentation for linkgit:git-receive-pack[1].
>      ++
>
>        OPTIONS[[OPTIONS]]
>        ------------------
>  2:  0ec629d403 ! 2:  3ecfb5c3a6 doc: add an UPSTREAM BRANCHES section to pull/push/fetch
>      @@ Commit message
>
>           Signed-off-by: Julia Evans <julia@jvns.ca>
>
>      - ## Documentation/git-fetch.adoc ##
>      -@@ Documentation/git-fetch.adoc: include::pull-fetch-param.adoc[]
>      -  Read refspecs, one per line, from stdin in addition to those provided
>      -  as arguments. The "tag <name>" format is not supported.
>      -
>      --include::urls-remotes.adoc[]
>      -+include::urls-remotes-upstreams.adoc[]
>      -
>      -
>      - CONFIGURED REMOTE-TRACKING BRANCHES[[CRTB]]
>      -
>      - ## Documentation/git-pull.adoc ##
>      -@@ Documentation/git-pull.adoc: include::fetch-options.adoc[]
>      -
>      - include::pull-fetch-param.adoc[]
>      -
>      --include::urls-remotes.adoc[]
>      -+include::urls-remotes-upstreams.adoc[]
>      -
>      - include::merge-strategies.adoc[]
>      -
>      -
>      - ## Documentation/git-push.adoc ##
>      -@@ Documentation/git-push.adoc: further recursion will occur. In this case, "only" is treated as "on-demand".
>      - --ipv6::
>      -  Use IPv6 addresses only, ignoring IPv4 addresses.
>      -
>      --include::urls-remotes.adoc[]
>      -+include::urls-remotes-upstreams.adoc[]
>      -
>      - OUTPUT
>      - ------
>      -
>      - ## Documentation/urls-remotes.adoc => Documentation/urls-remotes-upstreams.adoc ##
>      -@@ Documentation/urls-remotes-upstreams.adoc: git push uses:
>      + ## Documentation/urls-remotes.adoc ##
>      +@@ Documentation/urls-remotes.adoc: git push uses:
>         HEAD:refs/heads/<head>
>        ------------
>
>      @@ Documentation/urls-remotes-upstreams.adoc: git push uses:
>       +Git defaults to using the upstream branch for remote operations, for example:
>       +
>       +* It's the default for `git pull` or `git fetch` with no arguments
>      -+* It's sometimes the default for `git push` with no arguments. See the
>      -+  `push.default` section of linkgit:git-config[1] for the details.
>      -+* `git status` and `git branch -v` will show the
>      -+  relationship between the current branch and the upstream,
>      -+  for example "Your branch is up to date with origin/main"
>      ++* It's the default for `git push` with no arguments, with some exceptions.
>      ++  For example, you can use the `branch.<name>.pushRemote` option to push
>      ++  to a different remote than you pull from, and by default with
>      ++  `push.default=simple` the upstream branch you configure must have
>      ++  the same name.
>      ++* Various commands, including `git checkout` and `git status`, will
>      ++  show you how many commits have been added to your current branch and
>      ++  the upstream since you forked from it, for example "Your branch and
>      ++  'origin/main' have diverged, and have 2 and 3 different commits each
>      ++  respectively"
>       +
>       +The upstream is stored in `.git/config`, in the "remote" and "merge"
>       +fields. For example, if `main`'s upstream is `origin/main`:
>       +
>      -+```
>      -+[branch "main"]
>      -+   remote = origin
>      -+   merge = refs/heads/main
>      -+```
>      ++ [branch "main"]
>      ++    remote = origin
>      ++    merge = refs/heads/main
>       +
>       +You can set an upstream branch explicitly with
>       +`git push --set-upstream <remote> <branch>` or `git branch --track`,
>  3:  374740c678 ! 3:  bfd6072983 doc: git-push: clarify "where to push"
>      @@ Commit message
>           doc: git-push: clarify "where to push"
>
>           Be clearer about what we're describing ("which repository" instead of
>      -    "what to push"), and start with a positive "try X, then Y, then Z"
>      +    "where to push"), and start with a positive "try X, then Y, then Z"
>           instead of a negative ("if X is not specified..").
>
>           Signed-off-by: Julia Evans <julia@jvns.ca>
>
>        ## Documentation/git-push.adoc ##
>      -@@ Documentation/git-push.adoc: DESCRIPTION
>      - Updates one or more branches, tags, or other references in a remote
>      - repository from your local repository.
>      +@@ Documentation/git-push.adoc: Updates one or more branches, tags, or other references in a remote
>      + repository from your local repository, and sends all necessary data
>      + that isn't already on the remote.
>
>       -When the command line does not specify where to push with the
>       -`<repository>` argument, `branch.*.remote` configuration for the
>  4:  59732f1e47 = 4:  be6453d010 doc: git-push: clarify "what to push"
>
> --
> gitgitgadget